agentleFS
spupuzspupuz/VibeNVR/AGENTS.md

VibeNVR

AGENTS.md424 starsChanged 3 months agoMITView on GitHub

All AI agents must conform to CONTEXT.md VibeNVR is a lightweight, modern Network Video Recorder (NVR) built with Python (FastAPI) backend and React (Vite) frontend. It leverages Docker for orchestration and FFmpeg for video processing. CRITICAL RULE: AI Agents MUST NEVER run docker compose commands directly. Always ask the USER to run the rebuild commands manually. Key patterns: - Routers: Handle HTTP request/response, validation, and auth. - Services: Contain business logic. Called by routers. - CRUD: Strictly database operations. -…

  • Sends data out
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repositoryOne other file it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

21 rules. About 0 are common, 4 are distinctive, and 17 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 17

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Dependency Injection: Use Depends(database.get_db) and Depends(auth_service.get_current_active_admin).

    line 37
  2. Very specific:

    Localization: NEVER hardcode English strings in JSX.

    line 74
  3. Distinctive:

    Rule: All database interactions MUST use the SQLAlchemy ORM to ensure cross-dialect compatibility.

    line 117
  4. Very specific:

    Rule: NEVER use database-specific column types (like Postgres JSONB or ARRAY).

    line 118
  5. Very specific:

    Rule: NEVER write raw SQL queries (.execute(text(...))) that use dialect-specific functions (e.g., Postgres setval or pg_database_size) …

    line 119
  6. Very specific:

    All API calls — including media endpoints (/cameras/{id}/frame, /cameras/{id}/stream) — must use Authorization: Bearer ${token} in the …

    line 127
  7. Distinctive:

    All data models must use Pydantic schemas with validators where necessary (e.g., preventing path traversal).

    line 176
  8. Very specific:

    Rule: If the internal go2rtc Gateway is enabled globally, the stream URL is dynamically rewritten by the Backend to point to 127.0.0.1:8554 …

    line 202
  9. Very specific:

    Rule: If a Sub-Stream is configured, the system initializes an independent sub_stream_reader.

    line 203
  10. Very specific:

    When implementing passthrough recording using PyAV (especially versions 15+ built against FFmpeg 7+), strict packet temporal metadata …

    line 226
  11. Distinctive:

    Rule: All backup/restore endpoints must be Admin-only.

    line 240
  12. Very specific:

    Rule: Before falling back to hard deletion during emergency cleanup, the system must attempt to run archival if it is globally enabled …

    line 255
  13. Very specific:

    Rule: Use the ?raw=true query parameter with admin credentials to retrieve unmasked frames for the UI editor.

    line 266
  14. Very specific:

    All file deletions must be performed via the delete_event_files helper to ensure mandatory path sanitization and prevent traversal attacks.

    line 278
  15. Very specific:

    Rule: Use Paho MQTT v2.x callback signatures (5 parameters: client, userdata, flags, reason_code, properties).

    line 292
  16. Very specific:

    Rule: When adding new API endpoints or frontend API calls (e.g., using fetch), ensure they are compatible with the window.fetch proxy …

    line 312
  17. Very specific:

    Rule: All client implementations (Frontend, Python tests) must account for the p_type byte at offset 0.

    line 319
  18. Very specific:

    Rule: Always check window.isSecureContext before initializing VideoDecoder.

    line 324
  19. Very specific:

    Rule: If isSecureContext is false, the UI MUST provide a clear warning and fall back to JPEG polling.

    line 325
  20. Very specific:

    Good: Use def for blocking operations (FastAPI runs them in a threadpool).

    line 336
  21. Distinctive:

    Good: Use Tailwind utilities.

    line 348

≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

VibeNVR AI Agent Instructions

All AI agents must conform to CONTEXT.md

VibeNVR is a lightweight, modern Network Video Recorder (NVR) built with Python (FastAPI) backend and React (Vite) frontend. It leverages Docker for orchestration and FFmpeg for video processing.

Development Environment

docker compose down && docker compose up -d --build && docker compose logs --tail 100    # Rebuild/Restart the dev environment

CRITICAL RULE: AI Agents MUST NEVER run docker compose commands directly. Always ask the USER to run the rebuild commands manually.

Architecture Overview

Backend (backend/)

backend/
├── main.py           # App entry point, CORS config, exception handlers
├── models.py         # SQLAlchemy Database Models
├── schemas.py        # Pydantic Schemas for validation
├── crud.py           # Database CRUD operations
├── database.py       # DB connection & SessionLocal
├── routers/          # API Routes (cameras, events, settings, etc.)
└── *_service.py      # Business logic (motion, storage, auth, etc.)

Key patterns:

  • Routers: Handle HTTP request/response, validation, and auth.
  • Services: Contain business logic. Called by routers.
  • CRUD: Strictly database operations.
  • Dependency Injection: Use Depends(database.get_db) and Depends(auth_service.get_current_active_admin).

Engine (engine/)

engine/
├── core.py               # CameraManager & Webhook Event Dispatcher
├── camera_thread.py      # Main loop, coordinates components & frame processing
├── stream_reader.py      # PyAV RTSP connection, IP ban protection, WS broadcast
├── recording_manager.py  # FFmpeg subprocess management (Passthrough, Transcoding, HW accel)
├── motion_detector.py    # MOG2 background subtraction and motion analysis
├── mask_handler.py       # JSON polygon parsing and frame masking
└── overlay_handler.py    # OSD text overlays on frames

Key patterns:

  • Modular Components: camera_thread.py delegates IO and heavy processing to dedicated modules.
  • Resilience: stream_reader.py implements smart backoff (401/403 -> 5m, Refused -> 1m) to avoid IP bans on standard consumer cameras (e.g. Tapo/TP-Link).
  • Graceful Degradation: recording_manager.py falls back from Passthrough to software/HW encoding on failures.

Frontend (frontend/src/)

src/
├── components/       # Reusable UI components
├── pages/            # Main page views (routed)
├── contexts/         # React Contexts (Auth, Toast, etc.)
├── assets/           # Static assets
├── App.jsx           # Main App component & Routing logic
└── main.jsx          # Entry point

Key patterns:

  • Components: Functional React components with Hooks. Keep them small (<300 LOC preferred).
  • Modular Pages: Large pages (e.g., Cameras.jsx) must be decomposed into a directory (e.g., src/components/Cameras/) with sub-components for modals and complex UI sections.
  • Styling: TailwindCSS utility classes.
  • State Management: React useState and Context for global state (Auth).
  • Localization: NEVER hardcode English strings in JSX. Always use the t() hook from react-i18next (e.g., t('key', 'Default English')). Use extract_t.py and auto_translate.py in frontend/scripts/ to generate translations.
  • Icons: lucide-react for all icons.

Telemetry Worker (vibenvr-telemetry-worker/)

vibenvr-telemetry-worker/src/
├── index.js          # Main Cloudflare Worker entry point
├── api.js            # External API interactions
├── dashboard.js      # Status dashboard HTML rendering
├── ingest.js         # Telemetry data ingestion
├── security.js       # Security headers and CSP
└── assets.js         # Static asset delivery

Key patterns:

  • Cloudflare Worker: Runs at the edge, requiring lightweight ES modules.
  • Strict Modularity: Each file handles a single domain to respect the strict 1000 LOC policy.
  • Security Check: Enforces CSP and API token requirements natively on the edge before requests hit the origin.

Critical Patterns

FastAPI Route Pattern

Routes must use schemas for validation and Depends for database sessions.

# backend/routers/cameras.py (Pattern)
@router.post("", response_model=schemas.Camera)
def create_camera(
    camera: schemas.CameraCreate, 
    db: Session = Depends(database.get_db), 
    current_user: models.User = Depends(auth_service.get_current_active_admin)
):
    # Logic delegated to crud or service
    new_camera = crud.create_camera(db=db, camera=camera)
    motion_service.generate_motion_config(db)
    return new_camera

Database Agnostic Pattern

VibeNVR supports both PostgreSQL and SQLite.

  • Rule: All database interactions MUST use the SQLAlchemy ORM to ensure cross-dialect compatibility.
  • Rule: NEVER use database-specific column types (like Postgres JSONB or ARRAY). Use standard types (e.g., String for JSON data).
  • Rule: NEVER write raw SQL queries (.execute(text(...))) that use dialect-specific functions (e.g., Postgres setval or pg_database_size) without providing a fallback or explicitly checking if db.bind.dialect.name == 'postgresql':.

React Authentication Pattern

The frontend uses AuthContext to manage the JWT token in memory. Do not use localStorage for the token — it is vulnerable to XSS. The token is persisted across page reloads via a HttpOnly cookie (auth_token) set by the backend on login.

SSO / OAuth: VibeNVR supports logging in via external Identity Providers (IdP). This is handled via explicit account linking (the user or admin must map the OAuth Subject ID to a local account). Auto-provisioning is strictly disabled.

All API calls — including media endpoints (/cameras/{id}/frame, /cameras/{id}/stream) — must use Authorization: Bearer ${token} in the request headers. The media_token HttpOnly cookie is maintained as a secondary fallback but should never be the sole authentication mechanism.

// frontend/src/contexts/AuthContext.jsx (Pattern)
export const AuthProvider = ({ children }) => {
    // Token in memory ONLY — never in localStorage
    const [token, setToken] = useState(null);

    // On page reload: bootstrap session from HttpOnly cookie (server-side read)
    const bootstrapFromCookie = useCallback(async () => {
        const res = await fetch('/api/auth/me-from-cookie', { credentials: 'include' });
        if (res.ok) {
            const { user, access_token } = await res.json();
            setUser(user);
            setToken(access_token); // stored in memory, not localStorage
        }
    }, []);

    const login = (newToken, userData) => {
        setToken(newToken); // HttpOnly cookie already set by backend response
        setUser(userData);
        // No localStorage
    };

    const logout = async () => {
        setToken(null);
        setUser(null);
        await fetch('/api/auth/logout', { method: 'POST', credentials: 'include' });
    };
};

/**
 * NOTE: Cookie Security Policy
 * The backend uses 'COOKIE_SECURE=auto' by default. 
 * - If access is via HTTP (local IP), the 'Secure' flag is removed to allow sessions.
 * - If access is via HTTPS (remote proxy), the 'Secure' flag is automatically enabled.
 * This ensures zero-config local usability without compromising public security.
 */

// Correct pattern for media fetch (frame polling):
const response = await fetch(`/api/cameras/${id}/frame?t=${Date.now()}`, {
    credentials: 'include',
    headers: token ? { 'Authorization': `Bearer ${token}` } : {}
});

Pydantic Schema Validation

All data models must use Pydantic schemas with validators where necessary (e.g., preventing path traversal).

# backend/schemas.py (Pattern)
class CameraBase(BaseModel):
    name: str
    rtsp_url: str
    
    @field_validator('rtsp_url')
    @classmethod
    def validate_rtsp_url(cls, v: str) -> str:
        if v:
            v_lower = v.strip().lower()
            if not v_lower.startswith(('rtsp://', 'rtsps://', 'http://', 'https://')):
                raise ValueError('URL must start with valid protocols')
            if 'localhost' in v_lower or '127.0.0.1' in v_lower:
                raise ValueError('Localhost access is not allowed')
        return v

Camera Connection Pattern (IP Ban Protection)

To prevent cameras from banning the host IP due to rapid authentication retries (common on Tapo/TP-Link), use PyAV (av.open) for the connection attempt. PyAV provides native FFmpeg bindings that are more resilient than cv2.VideoCapture for RTSP streams.

  • Rule: A 401/403 result from av.open must enter a 5-minute backoff period.
  • Rule: Connection refused/reset errors should trigger a longer backoff (60-300s).
  • Rule: If the internal go2rtc Gateway is enabled globally, the stream URL is dynamically rewritten by the Backend to point to 127.0.0.1:8554 to proxy the connection. The Engine logs this explicit proxy path.
  • Rule: If a Sub-Stream is configured, the system initializes an independent sub_stream_reader. The CameraThread prioritizes frames from the sub-stream for the UI grid view to optimize bandwidth.
# engine/camera_thread.py (Pattern)
import av

# Main Stream Reader
self.stream_reader = StreamReader(url, transport, ...)
# Optional Sub Stream Reader
if sub_url:
    self.sub_stream_reader = StreamReader(sub_url, sub_transport, ...)

try:
    container = av.open(url, options={'rtsp_transport': 'tcp'}, timeout=8.0)
    # Success
except Exception as e:
    if "401" in str(e) or "unauthorized" in str(e).lower():
        self.health_status = "UNAUTHORIZED"
        # Enter 5-minute backoff

PyAV Muxing Pattern (Passthrough)

When implementing passthrough recording using PyAV (especially versions 15+ built against FFmpeg 7+), strict packet temporal metadata constraints apply when muxing into MP4 containers.

  • Rule: NEVER use add_stream_from_template for segmented recording. It implicitly copies the duration and start_time of the live connection's AVStream. For segmented MP4 files (e.g., 1-minute chunks), this causes the file duration to exponentially accumulate (1m, 2m, 3m). Always use .add_stream(in_stream.name) and manually copy the extradata and time_base.
  • Rule: FFmpeg 7 strictly rejects packets with None as dts or pts when muxing to MP4 containers, raising [Errno 22] Invalid argument. You MUST manually normalize the initial timestamps to 0 if they evaluate to None.
  • Rule: The pre-buffer packet_ring_buffer MUST evaluate expiry using OS time (time.time()) rather than the packet's pts or time_sec. Jittery streams or connection restarts can reset pts to 0 (or None), poisoning the ring buffer with a massive negative expiry delta, causing it to leak memory indefinitely and rigurgitate the entire stream history at the start of every new MP4 segment.
  • Rule: When using av.BitStreamFilterContext (e.g., h264_mp4toannexb), the .filter(packet) method consumes/steals the C-level buffer of the original av.Packet. If the original packet is needed for a ring buffer or another thread, you MUST pass a copy (av.Packet(packet)) to the BSF, or else downstream consumers will silently receive empty (0-byte) packets, breaking muxing and decoding.
  • Rule: PyAV's MP4 muxer requires packets to be in AVCC format (4-byte length prefixes). If a camera outputs raw Annex-B packets (e.g., OEM cameras relying on SDP SPS/PPS), feeding these directly to container.mux() will result in corrupted/black MP4 files because the avcC atom will contain Annex-B data instead of AVCC data. Passthrough MUST be disabled for these streams so they are transcoded, or a dedicated mkv/ts container must be used instead.

Configuration Backup & Restore Pattern

The system supports full configuration backups (Cameras, Settings, Groups, Users, Storage Profiles) stored in JSON format within /data/backups/.

  • Rule: Standard retention policy (default 10 files) applies ONLY to automatic backups (AUTO).
  • Rule: Manual backups (MANUAL) are preserved indefinitely until user deletion.
  • Rule: On startup, the BackupSchedulerThread checks for existing recent backups and skips the immediate run if the interval has not passed (to avoid spamming during restarts).
  • Rule: All backup/restore endpoints must be Admin-only.
# backend/routers/settings.py (Pattern)
@router.post("/backup/run")
def manual_backup(db: Session = Depends(database.get_db), current_user: models.User = Depends(auth_service.get_current_active_admin)):
    backup_service.run_backup(is_manual=True)
    return {"message": "Manual backup completed successfully"}

Storage Routing & Archival Pattern

Cameras can be assigned independent storage profiles for specific event types (Motion, Continuous, Snapshot, Archive) to utilize tiered storage layers.

  • Rule: Archival is processed in an independent phase within the storage_monitor_loop to ensure moving files over slow network mounts does not block emergency space recovery.
  • Rule: Before falling back to hard deletion during emergency cleanup, the system must attempt to run archival if it is globally enabled (archival_enabled == "true").
  • Rule: Paths constructed for archival MUST use translate_path to guarantee traversal safety before moving files on the host filesystem.

Privacy Masking & Motion Zones Pattern

Privacy masks and motion zones are stored as JSON strings in the database and synced to the engine.

  • Rule: Privacy masks are applied before any other processing (recording, motion).
  • Rule: Motion zones are used strictly for motion exclusion and do not obscure video.
  • Rule: passthrough_recording must be disabled if privacy masks are active to allow burning masks into the stream.
  • Rule: Use the ?raw=true query parameter with admin credentials to retrieve unmasked frames for the UI editor.
# backend/routers/cameras.py
@router.get("/{camera_id}/frame")
def get_camera_frame(camera_id: int, raw: bool = False, ...):
    # If raw=true and admin, fetch unmasked frame from engine
    pass

Event Deletion & Path Traversal Pattern

All file deletions must be performed via the delete_event_files helper to ensure mandatory path sanitization and prevent traversal attacks.

# backend/routers/events.py (Pattern)
def delete_event_files(event: models.Event) -> int:
    # 1. Map container paths (/var/lib/...) to backend paths (/data/...)
    # 2. MANDATORY: Verify path safety using `event_file_service.is_path_safe(path, db)`
    # 3. Securely remove file and return bytes deleted

MQTT Service & Home Assistant Discovery Pattern

The MQTT service provides real-time event reporting and integration with Home Assistant.

  • Rule: Use Paho MQTT v2.x callback signatures (5 parameters: client, userdata, flags, reason_code, properties).
  • Rule: Discovery on Connect: Always trigger publish_discovery for all active cameras immediately upon a successful connection to the broker.
  • Rule: Async Logic: Use client.connect_async and client.loop_start to prevent blocking the Engine's main lifecycle.
  • Rule: Discovery Logic: Discovery payloads must be sent as retain=True to the homeassistant/binary_sensor/ topic.
# engine/mqtt_service.py (Pattern)
def _on_connect(self, client, userdata, flags, reason_code, properties=None):
    if reason_code == 0:
        self.connected = True
        # Send discovery for all cameras immediately on connection
        for camera_id, thread in manager.cameras.items():
            self.publish_discovery(camera_id, thread.config.get("name"))

Federation Architecture Pattern

VibeNVR supports a decentralized multi-node Federation where a Master Node can proxy requests to Remote Nodes.

  • CRITICAL RULE: Anything that works locally (on the Master) MUST also work perfectly across the Federation proxy when a remote Node is selected.
  • Rule: When adding new API endpoints or frontend API calls (e.g., using fetch), ensure they are compatible with the window.fetch proxy interceptor (frontend/src/main.jsx) and the backend proxy router (backend/routers/federation.py).
  • Rule: Authentication for proxied API requests is handled by extracting the master's JWT token, translating it to the remote node's X-API-Key, and forwarding the request. Do not hardcode authorization assumptions that break this flow.

WebSocket 10-byte Hybrid Protocol

VibeNVR uses a standardized 10-byte binary header for all streaming packets to ensure low-latency multiplexing.

  • Format: struct.pack('<BBd', p_type, is_keyframe, timestamp)
  • Types: 0 (Video), 1 (Audio), 2 (Metadata/AI).
  • Rule: All client implementations (Frontend, Python tests) must account for the p_type byte at offset 0.
  • Rule: AI metadata packets (pType 2) contain JSON strings for client-side rendering.

Secure Context & Fallback Policy

To comply with browser security requirements, high-performance APIs (WebCodecs) are restricted to Secure Contexts (HTTPS/localhost).

  • Rule: Always check window.isSecureContext before initializing VideoDecoder.
  • Rule: If isSecureContext is false, the UI MUST provide a clear warning and fall back to JPEG polling.

Anti-Patterns to Avoid

Anti-Pattern 1: Blocking Async Logic

Bad: Performing blocking I/O (DB, File) inside an async def function in FastAPI.

@router.get("/")
async def read_items(db: Session = Depends(get_db)):
    return db.query(models.Item).all()  # BLOCKING! Freezes the event loop.

Good: Use def for blocking operations (FastAPI runs them in a threadpool).

@router.get("/")
def read_items(db: Session = Depends(get_db)):
    return db.query(models.Item).all()  # Safe.

Anti-Pattern 2: Hardcoded Styles

Bad: Using custom CSS or inline styles when Tailwind exists.

<div style={{ padding: '20px', backgroundColor: 'red' }}>Error</div>

Good: Use Tailwind utilities.

<div className="p-5 bg-red-500 text-white">Error</div>

Anti-Pattern 3: Ignoring RBAC

Bad: Creating sensitive endpoints without checking user role.

@router.delete("/camera/{id}")
def delete_camera(id: int, db: Session = Depends(get_db)):
    # Anyone can delete!

Good: Require appropriate role (e.g., Admin).

@router.delete("/camera/{id}")
def delete_camera(
    id: int, 
    db: Session = Depends(get_db),
    current_user: models.User = Depends(auth_service.get_current_active_admin)
):
### Anti-Pattern 4: Raw Logs
**Bad**: Logging sensitive data (URLs with credentials, tokens) directly without context.
```python
logger.info(f"Connecting to {rtsp_url}") # BAD! Exposes credentials in stdout.

Good: While the centralized log router (backend/routers/logs.py) automatically masks stdout logs, it is best practice to sanitize URLs before logging using re.sub.

safe_url = re.sub(r'://([^:]+):([^@]+)@', r'://\1:***@', rtsp_url)
logger.info(f"Connecting to {safe_url}")

Note: VibeNVR uses a centralized TokenRedactingFilter (defined in backend/main.py) that automatically masks credentials, Bearer tokens, and API keys at the root logger level. Always ensure new loggers inherit from this filter to maintain auditability without leaking secrets.

Anti-Pattern 5: Memory Bloat on Bulk Queries

Bad: Fetching thousands of rows into Python memory at once, risking OOM (Out Of Memory) crashes.

all_events = db.query(Event).filter(Event.type == "video").all() # BAD! Loads all records into memory.

Good: Use .yield_per(1000) to stream results in manageable chunks.

all_events = db.query(Event).filter(Event.type == "video").yield_per(1000) # SAFE!

Security & Data Privacy

CRITICAL: All AI agents must read and strictly adhere to SECURITY.md.

  • Sanitize everything: Every input from the user or the network must be validated using Pydantic schemas.
  • Mask logs and telemetry: Ensure that no sensitive information is ever written to logs or telemetry streams.
  • No Absolute Host Paths: Never hardcode absolute host paths (e.g., /absolute/path/to/repo/...). All paths in documentation must be relative or dynamically resolved.
  • Role-Based Access Control (RBAC): Always check for current_user role when implementing new API endpoints.

AI-Assisted Contributions

Required Reading

  1. Must read: CONTEXT.md and SECURITY.md
  2. Must follow: Code conventions (Python PEP8, React Hooks rules).

Developer Guidelines

  • Testing: Before any verification (automated or manual), always perform a full rebuild to ensure all changes are active. DO NOT run this yourself; ask the USER to run it:
    docker compose down && docker compose up -d --build && docker compose logs --tail 100
  • Commits: Always run local tests (/run-tests.md or manual pytest) AND perform manual verification (human UX check) after a full rebuild before committing. Never commit failing code or unverified UI changes. Wait for explicit USER confirmation after manual verification before committing.
  • Automated Tests (New Features): If you implement a new feature or functionality, you MUST explicitly write new automated test scripts to verify it. NEVER create a root tests or test folder. Use the following locations:
    • Local/Throwaway tests: Save these in scripts/security_tests/ or scripts/tests/ (this folder is ignored by both Git and Docker to keep the repo clean). CRITICAL RULE: Any other temporary files, scratchpads, or throwaway scripts created outside of these local folders MUST be strictly removed and NEVER committed.
    • CI Integration tests: If the test must run automatically on GitHub Actions, save it in .github/scripts/ (this folder is tracked by Git so the CI can access it, but is excluded from Docker images to prevent bloat). The tests must cover:
    1. Security (RBAC, missing auth, exposed data)
    2. Regression (ensure existing logic is not broken)
    3. Functioning (verify the new logic works as expected) All scripts must implement safe cleanup logic.
  • Pushes: Do NOT push to remote repositories unless explicitly requested by the USER. CRITICAL: For VibeNVR-site and vibenvr-telemetry-worker repositories, NEVER commit or push autonomously. You MUST exclusively use the /site-telemetry-commit-push workflow and wait for explicit permission.
  • Documentation: Keep documentation synced with code changes.
  • Code Size Policy:
    • New files: MUST NOT exceed 500 effective lines of code (excluding comments/blank lines).
    • Existing files (Legacy): MUST NOT exceed 1000 effective lines of code. If reached, the file must be refactored into smaller modules.
    • Enforcement: This is strictly enforced via the check_effective_loc.py assurance script. Any violation will fail the security audit workflow.

Contribution Template

## Summary
[Description of changes]

## Changes
- [File/Component]: [Change details]

## Verification
- [ ] Docker build successful
- [ ] Backend logs clear of errors
- [ ] UI tested on Desktop & Mobile

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.