onecrawl 4.0.0-alpha.37

package/assets/skills/onecrawl-commands/SKILL.md

@@ -0,0 +1,447 @@
+---
+name: onecrawl-commands
+description: "Complete guide to OneCrawl CLI commands. Use primitives first, eval only as fallback."
+---
+# OneCrawl Commands Skill
+
+## Core Principle
+
+**Always use OneCrawl primitives first. Use `eval` only as a last resort.**
+
+OneCrawl provides 500+ typed, validated CLI commands and 546 MCP tool actions
+across 18 tools. Each one is faster, safer, and more debuggable than raw JavaScript
+evaluation. Reserve `eval` for cases where no primitive exists.
+
+## Decision Flowchart
+
+```
+Need to interact with a page?
+  ├─ Navigation?        → navigate, back, forward, reload
+  ├─ Read content?      → get text/html/url/title/value/attr/count
+  ├─ Click something?   → click, find text/role/label <target> click
+  ├─ Fill a form?       → fill, type, select-option, check/uncheck
+  ├─ Wait for state?    → wait-for-selector, wait-for-text, wait-for-load
+  ├─ Take screenshot?   → screenshot --full, screenshot --element <sel>
+  ├─ Extract data?      → extract content json, extract metadata
+  ├─ Cookie ops?        → cookie get/set/delete/export/import
+  ├─ Auth state?        → auth-state save/load, account export/import
+  ├─ Passkeys?          → auth passkey-enable/register, auth vault-list
+  ├─ Network control?   → network block, throttle, route, intercept
+  ├─ HAR/traffic?       → har start/drain/export, network-log start/drain
+  ├─ Domain blocking?   → domain block/unblock/stats/list/categories
+  ├─ Proxy?             → proxy create-pool, proxy-health check/rank
+  ├─ Coverage?          → coverage js-start/stop, css-start/report
+  ├─ Performance?       → perf trace-start/stop, metrics, timing
+  ├─ Accessibility?     → a11y tree/element/audit
+  ├─ Workers/iframes?   → worker list, iframe list/eval/content
+  ├─ Page changes?      → page-watcher start/drain/stop/state
+  ├─ Visual diff?       → diff screenshot/url, screenshot-diff
+  ├─ HTTP requests?     → request execute/batch
+  ├─ Stealth?           → stealth inject, stealth detection-audit
+  ├─ None of the above? → eval "<js expression>"  ← LAST RESORT
+```
+
+## Command Categories
+
+### 1. Session Management (start here)
+```bash
+session start                    # Default: daemon mode, normal Chrome
+session start --engine lightpanda # Lightpanda browser engine
+session start --session work     # Named session (multi-session)
+session start -H                 # Headless mode
+session start --shared-browser   # Incognito context in parent session
+session start --import-passkey FILE  # Auto-inject passkeys on connect
+session info                     # Show active session
+session close                    # Close session
+```
+
+**Multi-agent isolation** (enabled by default via `session_auto_isolate`):
+- Each agent auto-gets a unique session name (e.g. `default-2`, `default-3`)
+- Session files use advisory locks (fcntl) to prevent corruption
+- Session writes are atomic (tmp + rename pattern)
+- `--shared-browser` creates an isolated BrowserContext in a parent session
+
+### 2. Navigation (most common)
+```bash
+navigate <url>                   # Go to URL
+navigate <url> --wait 2000       # Wait 2s after load
+navigate <url> --wait-cf         # Wait for Cloudflare challenge
+back                             # Browser back
+forward                          # Browser forward
+reload                           # Reload page
+```
+
+### 3. Content Reading (prefer over eval)
+```bash
+get text <selector>              # Get text content ← USE THIS, not eval
+get html <selector>              # Get innerHTML
+get url                          # Current URL
+get title                        # Page title
+get value <selector>             # Input value
+get attr <selector> <name>       # Element attribute
+get count <selector>             # Count matching elements
+get styles <selector>            # Computed styles
+```
+
+**Why not eval?** `get text h1` is typed, validated, and returns clean output.
+`eval "document.querySelector('h1').textContent"` can throw, returns raw JSON,
+and is harder to debug.
+
+### 4. Element Interaction (typed and safe)
+```bash
+click <selector>                 # Click
+dblclick <selector>              # Double-click
+fill <selector> <text>           # Fill input (clears first)
+type <selector> <text>           # Type into element (appends)
+hover <selector>                 # Mouse hover
+focus <selector>                 # Focus element
+scroll-into-view <selector>     # Scroll to element
+check <selector>                 # Check checkbox
+uncheck <selector>               # Uncheck checkbox
+select-option <selector> <val>   # Select dropdown
+upload <selector> <file>         # Upload file
+drag <from_sel> <to_sel>        # Drag and drop
+```
+
+### 5. Smart Finders (no CSS selectors needed)
+```bash
+find text "Submit" click         # Click by visible text
+find role button click --name "Login"  # Click by ARIA role
+find label "Email" fill "user@example.com"  # Fill by label
+find placeholder "Search..." fill "query"   # Fill by placeholder
+find test-id "submit-btn" click  # Click by data-testid
+find first ".item" click         # First matching element
+find nth 3 ".item" click         # Nth element (0-based)
+```
+
+**Why finders?** They mirror how users think about the page — by visible text,
+labels, and roles — not by CSS internals that break on refactors.
+
+### 6. Waiting (explicit, not sleep)
+```bash
+wait-for-selector <selector>     # Wait for element
+wait-for-selector <sel> --timeout 10000  # Custom timeout
+wait-for-text <text>             # Wait for text to appear
+wait-for-url <url_part>         # Wait for navigation
+wait-for-load networkidle       # Wait for network idle
+wait-for-function "window.ready" # Wait for JS condition
+wait 1000                        # Raw delay (avoid when possible)
+```
+
+### 7. Screenshots & Visual
+```bash
+screenshot                       # Viewport screenshot
+screenshot --full                # Full page
+screenshot --element <selector>  # Element only
+screenshot --output /path.png   # Save to file
+screenshot --annotate           # With element annotations
+pdf --output page.pdf           # Save as PDF
+```
+
+### 8. Cookie Management
+```bash
+cookie get                       # List all cookies (CDP, includes httpOnly)
+cookie get --name session_id    # Specific cookie
+cookie set name value --domain .example.com
+cookie delete name .example.com
+cookie clear                     # Clear all
+cookie export --output cookies.json
+cookie import cookies.json
+```
+
+### 9. Auth State Persistence
+```bash
+auth-state save <name>           # Save cookies + localStorage + sessionStorage + URL (v2)
+auth-state load <name>           # Restore full auth state via CDP
+auth-state list                  # Show all saved states
+auth-state show <name>           # Display JSON content
+auth-state rename <old> <new>
+auth-state clear <name>          # Delete specific
+auth-state clean                 # Delete all
+```
+
+**Auth state v2 format** stores full CDP cookies (including httpOnly, SameSite, secure)
+plus localStorage, sessionStorage, and the page URL. Auto-detects and handles v1 files.
+
+### 10. Account Management (portable bundles)
+```bash
+account export <name>                    # Bundle auth state + passkeys
+account export <name> --auth-state alt   # Use different auth state name
+account export <name> --rp-id x.com      # Export only specific site passkeys
+account import /path/to/bundle.json      # Restore auth state + merge passkeys
+account list                             # Show all account bundles
+account show <name>                      # Display bundle details
+account delete <name>                    # Remove a bundle
+```
+
+**Account bundles** combine auth state (cookies + localStorage + sessionStorage + URL)
+with passkey credentials into a single portable JSON file at `~/.onecrawl/accounts/`.
+
+### 11. Passkey & WebAuthn (CDP-only, real ECDSA signatures)
+```bash
+auth passkey-enable              # Enable CDP virtual authenticator
+auth passkey-register --output /tmp/passkeys.json  # Watch + export credentials
+auth passkey-add --credential-id <b64> --rp-id <domain>
+auth passkey-list                # List active credentials
+auth passkey-log                 # Show WebAuthn operation log
+auth passkey-disable             # Disable virtual authenticator
+auth passkey-remove --credential-id <b64>
+auth passkey-set-file --file <path>  # Auto-inject on reconnect
+
+# Vault (persistent multi-site storage)
+auth vault-list                  # List all sites + credential counts
+auth vault-save --input <json>   # Save passkeys to vault
+auth vault-export --rp-id x.com --output /tmp/out.json
+auth vault-remove --credential-id <b64>
+auth vault-clear-site --rp-id x.com
+
+# Import from password managers
+auth import-bitwarden --input export.json   # Bitwarden JSON export
+auth import-one-password --input export.data # 1Password .1pux extract
+auth import-cxf --input cxf.json            # FIDO Alliance CXF format
+```
+
+**Architecture**: All passkey operations use real Chrome CDP WebAuthn domain
+(not JS injection). ECDSA P-256 signatures are valid for server verification.
+Vault stored at `~/.onecrawl/passkeys/vault.json` with atomic writes.
+
+### 12. Stealth & Anti-Detection
+```bash
+stealth inject                   # Full stealth patch suite (auto on session start)
+stealth detection-audit          # Run comprehensive bot detection check
+stealth tls-apply <profile>      # TLS fingerprint: chrome, firefox, safari, edge
+stealth webrtc-block             # Prevent IP leaks via WebRTC
+stealth battery-spoof            # Spoof BatteryManager API
+stealth sensor-block             # Block motion/orientation sensors
+stealth canvas-advanced          # Gaussian canvas noise (not 1-bit XOR)
+stealth timezone-sync <tz>       # Sync Date + Intl + navigator timezone
+stealth font-protect             # Block font fingerprinting
+stealth behavior-sim             # Start continuous human behavior simulation
+stealth behavior-stop            # Stop simulation
+stealth stealth-rotate           # Auto-rotate fingerprint on domain change
+```
+
+**Stealth is injected automatically** on every new page/tab. 12 patches cover:
+navigator.webdriver, chrome.runtime, plugins, WebGL, permissions, toString,
+iframe isolation, dimensions, hardware concurrency, language, platform, codecs.
+
+### 13. Network Control
+```bash
+network block image,font        # Block resource types
+throttle set 3g                 # Throttle to 3G
+route "*.analytics.com" --block # Block specific domains
+intercept set '<rules_json>'    # Custom interception
+har start                       # Record HAR
+har drain                       # Drain HAR entries
+har export --output traffic.har # Export HAR
+network-log start               # Start structured network logging
+network-log drain               # Get captured entries
+network-log summary             # Traffic summary (by type, domain, size)
+network-log stop                # Stop logging
+network-log export --output log.json  # Export to file
+ws start                        # Start WebSocket capture
+ws drain                        # Get captured frames
+ws export --output ws.json      # Export frames
+ws connections                  # Count active WS connections
+```
+
+### 14. Domain Blocking
+```bash
+domain block example.com analytics.io  # Block specific domains
+domain block-category ads              # Block by category (ads, analytics, social, trackers)
+domain unblock                         # Clear all blocks
+domain stats                           # Blocked request statistics
+domain list                            # List all blocked domains
+domain categories                      # Show available categories + domain counts
+```
+
+### 15. Proxy Management
+```bash
+proxy create-pool '<json>'      # Create proxy rotation pool
+proxy chrome-args '<json>'      # Get Chrome args for proxy
+proxy next '<json>'             # Get next proxy from pool
+proxy-health check <url>        # Check single proxy health
+proxy-health check-all '<json>' # Batch health check
+proxy-health rank '<json>'      # Rank by score
+proxy-health filter '<json>'    # Filter healthy proxies
+```
+
+### 16. Accessibility & Debugging
+```bash
+a11y tree                        # Full accessibility tree
+a11y element <selector>          # Element accessibility info
+a11y audit                       # Accessibility audit (issues + recommendations)
+errors                           # Page errors
+console start && console drain   # Console messages
+highlight <selector>             # Visual highlight (3s red outline)
+snapshot agent --compact         # Agent-readable page snapshot
+```
+
+### 17. Code Coverage
+```bash
+coverage js-start               # Start JS coverage collection
+coverage js-stop                # Stop + get coverage report
+coverage css-start              # Start CSS coverage collection
+coverage css-report             # Get CSS coverage data
+```
+
+### 18. Performance Profiling
+```bash
+perf trace-start                # Start CDP performance tracing
+perf trace-stop                 # Stop + get trace data
+perf metrics                    # Get real-time performance metrics
+perf timing                     # Navigation timing breakdown
+perf resources                  # Resource timing for all loaded assets
+```
+
+### 19. Service Workers & Iframes
+```bash
+worker list                     # List active service workers
+worker unregister               # Unregister all service workers
+worker info                     # Detailed worker information
+
+iframe list                     # List all iframes with URLs
+iframe eval <index> '<expr>'    # Evaluate JS in specific iframe
+iframe content <index>          # Get iframe HTML content
+```
+
+### 20. Page Monitoring
+```bash
+page-watcher start              # Start DOM change tracking
+page-watcher drain              # Get captured changes since last drain
+page-watcher stop               # Stop watching
+page-watcher state              # Get current page state snapshot
+```
+
+### 21. Print & PDF Export
+```bash
+print pdf --output doc.pdf      # Export page as PDF
+print pdf --landscape --scale 0.8  # Landscape, custom scale
+print metrics                   # Get print layout metrics
+```
+
+### 22. Benchmarks & Rate Limiting
+```bash
+bench run --iterations 20       # Run CDP benchmarks
+bench report                    # Format benchmark results
+
+rate-limit set --preset cautious  # Apply rate limit preset
+rate-limit stats                # Current rate limit state
+rate-limit reset                # Reset counters
+```
+
+### 23. Visual Diff & Screenshots
+```bash
+diff snapshot                   # Take accessibility snapshot for diffing
+diff screenshot <baseline>      # Compare current page vs baseline screenshot
+diff url <url1> <url2>          # Compare two URLs (DOM diff)
+screenshot-diff compare <base> <current>  # Pixel diff two images
+screenshot-diff regression <baseline_dir>  # Visual regression test
+```
+
+### 24. HTTP Requests (in-browser)
+```bash
+request execute '<json>'        # Execute HTTP request via browser fetch
+request batch '<json>'          # Batch multiple requests
+fingerprint apply <profile>     # Apply fingerprint profile
+fingerprint detect              # Detect current browser fingerprint
+```
+
+### 25. Multi-Session & Daemon
+```bash
+daemon start                     # Start daemon (auto on session start)
+daemon exec goto url=https://example.com --session linkedin
+daemon exec evaluate expression="1+1" --session work
+daemon status                    # Daemon health + session list
+daemon stop                      # Stop daemon
+```
+
+### 26. Agent Automation
+```bash
+agent auto "<goal>"              # Autonomous goal execution
+agent auto "find the login button and click it" --max-steps 5
+agent loop                       # Observation monitor with goal verification
+agent think                      # Analyze page state, recommend actions
+agent chain "<js actions>"       # Execute pre-written action sequences
+agent observe                    # Get annotated page state with coordinates
+```
+
+## Anti-Patterns (Don't Do This)
+
+| ❌ Bad (eval) | ✅ Good (primitive) |
+|---|---|
+| `eval "document.title"` | `get title` |
+| `eval "document.querySelector('#btn').click()"` | `click #btn` |
+| `eval "document.querySelector('input').value = 'text'"` | `fill input text` |
+| `eval "document.querySelectorAll('li').length"` | `get count li` |
+| `eval "window.location.href"` | `get url` |
+| `eval "document.cookie"` | `cookie get` |
+| `eval "window.scrollTo(0, 999)"` | `scroll down 999` |
+
+## When eval IS appropriate
+
+- Custom business logic: `eval "calculateTotal(items)"`
+- Complex DOM traversal not covered by selectors
+- Reading `window.*` globals not exposed by primitives
+- Injecting scripts for testing (mocking APIs, etc.)
+
+## Configuration
+
+OneCrawl loads defaults from `~/.onecrawl/config.toml`:
+
+```toml
+engine = "chrome"               # or "lightpanda"
+headless = false
+daemon = true                   # daemon mode by default
+daemon_headless = true
+session_name = "default"
+session_auto_isolate = true     # auto-unique session names per agent
+persist_cookies = ""            # auto-persist path, empty = disabled
+chrome_profile = ""             # empty = auto (~/.onecrawl/chrome-profile/)
+user_agent = ""                 # empty = auto
+daemon_idle_timeout = 1800      # 30 minutes
+daemon_max_sessions = 8
+daemon_pool_size = 0            # pre-warmed sessions (0 = disabled)
+daemon_rate_limit = 0           # per-second (0 = unlimited)
+```
+
+CLI flags always override config values.
+
+## MCP Tool Reference (546 actions, 18 tools)
+
+When using OneCrawl via MCP (Model Context Protocol), all actions are available
+through `onecrawl run <tool> <action> --json`. The tools are:
+
+| Tool | Actions | Description |
+|------|---------|-------------|
+| `browser` | 196 | Navigation, interaction, extraction, network, coverage, performance, accessibility |
+| `agent` | 111 | Autonomous agent, skills, memory, planning, auto-login |
+| `secure` | 40 | Auth state, account bundles, passkey vault, imports, stealth |
+| `data` | 27 | Pipeline processing, export, transform |
+| `automate` | 27 | Scheduler, retry queues, session pool |
+| `stealth` | 25 | Bot detection, CAPTCHA, fingerprint, stealth patches |
+| `computer` | 24 | Computer-use API, screen coordinates, mouse/keyboard |
+| `daemon` | 22 | Daemon control, session management, pool config |
+| `crawl` | 5 | Spider, robots.txt, sitemap, DOM snapshots |
+| `vault` | 9 | Encrypted KV storage, PKCE, TOTP |
+| `plugin` | 9 | Plugin management |
+| `memory` | 6 | Long-term agent memory |
+| `perf` | 8 | Performance monitoring, budgets, regressions |
+| `durable` | 8 | Crash-safe sessions |
+| `reactor` | 8 | Event-driven automation rules |
+| `events` | 8 | Event bus, webhooks |
+| `studio` | 8 | Recording, playback |
+| `orchestrator` | 5 | Multi-agent coordination |
+| `vision` | — | Computer vision (experimental) |
+
+## File Layout
+
+```
+~/.onecrawl/
+├── config.toml                  # Global config
+├── auth-states/{name}.json      # Auth state snapshots (v2: CDP cookies + storage)
+├── accounts/{name}.json         # Account bundles (auth state + passkeys)
+├── passkeys/vault.json          # Multi-site passkey vault (rp_id → credentials)
+├── chrome-profile/              # Persistent Chrome profile
+└── profiles/{name}/             # Named browser profiles
+```

package/assets/skills/planning-tracking/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: planning-tracking
+description: "Execution plan with milestone/issue hierarchy, explicit dependencies, and safe parallelism."
+---
+# Planning & Tracking Skill
+
+## Purpose
+Create and maintain an execution plan with milestone/issue hierarchy, explicit dependencies, and safe parallelism.
+
+## Use when
+- Starting any non-trivial task
+- Scope changes during execution
+- Multiple files/workstreams must be coordinated
+
+## Mandatory Schema
+```typescript
+interface Plan { PRD: string; context: string; milestones: Record<string, Milestone>; }
+interface Milestone { id: string; description: string; priority: "critical"|"high"|"medium"|"low"; status: "todo"|"in_progress"|"review"|"done"; depends_on: string[]; issues: Record<string, Issue>; }
+interface Issue { id: string; task: string; priority: "critical"|"high"|"medium"|"low"; status: "todo"|"in_progress"|"review"|"done"|"blocked"; depends_on: string[]; children: Record<string, Issue>; }
+```
+
+## Procedure
+1. Build plan before implementation.
+2. Assign unique IDs to milestones/issues.
+3. Declare dependencies for every issue (`depends_on`).
+4. Execute by dependency order, then priority (`critical` → `high` → `medium` → `low`).
+5. Run independent same-priority milestones in parallel when safe.
+6. Update statuses continuously and append concise progress summaries.
+
+## Done Criteria
+- Plan exists, is up-to-date, and reflects actual execution state.
+- Dependencies are respected and parallel work is safe.
+
+## Anti-patterns
+- Starting implementation without a plan
+- Missing dependency declarations
+- Running blocked items in parallel

package/assets/skills/policy-coherence-audit/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: policy-coherence-audit
+description: "Detect and remove contradictions across agent policies before execution."
+---
+# Policy Coherence Audit Skill
+
+## Purpose
+Detect and remove contradictions across agent policies before execution.
+
+## Use when
+- Updating `AGENTS.MD`
+- Merging new workflow rules
+- Noticing behavioral ambiguity during execution
+
+## Checklist
+- Language coherence: English-only wording.
+- Interaction coherence: one question + 5-option model is consistently respected.
+- Gate coherence: completion gates apply to both Non-Breaking and Breaking paths.
+- Scope coherence: avoid wording that causes uncontrolled scope creep.
+- Reference coherence: every mentioned skill path exists.
+
+## Short examples
+- Fix mixed language term: "TASSATIVO" -> "MANDATORY".
+- Fix model mismatch: "propose one option" -> explicit 5-option decision set.
+
+## Anti-patterns
+- Leaving ambiguous precedence between structural and surgical strategies
+- Contradictory clauses in different sections
+- Referencing non-existent skill files

package/assets/skills/programmatic-tool-calling/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: programmatic-tool-calling
+description: "Multi-step tool workflows via code orchestration to reduce latency, context pollution, and token overhead."
+---
+# Programmatic Tool Calling Skill (Model-Agnostic)
+
+## Purpose
+Execute multi-step tool workflows via code orchestration to reduce latency, context pollution, and token overhead.
+
+## Use when
+- 3+ dependent tool calls
+- Large intermediate outputs (logs, tables, files)
+- Branching logic, retries, or fan-out/fan-in workflows
+
+## Core Idea
+Treat tools as callable functions inside an orchestration runtime (script/runner), not as one-turn-at-a-time chat actions.
+
+## Procedure
+1. Generate/execute orchestration code for loops, conditionals, parallel calls, retries, and early termination.
+2. Process intermediate data in runtime (filter/aggregate/transform) instead of returning raw data to model context.
+3. Return only high-signal outputs to the model (summary, decision, artifact references).
+
+## Why It Works (provider/model independent)
+- Fewer model round-trips for multi-call workflows.
+- Intermediate data stays out of context unless needed.
+- Explicit code control flow is easier to test, monitor, and debug.
+
+## Guardrails
+- Strict input/output schemas.
+- Validate tool results before use.
+- Idempotent/retry-safe tool design when possible.
+- Timeout/cancellation/expiry handling.
+- Sandbox execution for untrusted code; never blindly execute external payloads.
+
+## Done Criteria
+- Workflow completes with reduced context load and deterministic control flow.
+
+## Anti-patterns
+- Returning raw intermediate payloads to the model by default
+- Unbounded loops without stop conditions
+- Executing unvalidated tool output

package/assets/skills/rollback-rca/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: rollback-rca
+description: "Stop ineffective iteration loops and choose a controlled recovery path after repeated gate failures."
+---
+# Rollback & RCA Skill
+
+## Purpose
+Stop ineffective iteration loops and choose a controlled recovery path after repeated gate failures.
+
+## Use when
+- An issue fails completion gate 3 consecutive times
+
+## Procedure
+1. Stop work on the issue immediately.
+2. Run root cause analysis:
+   - Architecture mismatch?
+   - Dependency/environment problem?
+   - Scope too broad?
+3. Present options via `ask_user`:
+   - Rescope (split into smaller sub-issues)
+   - Rollback (revert to last known good commit)
+   - Redesign (change architecture)
+4. Execute selected path and document rationale in session log.
+
+## Rollback Rules
+- Keep history clean and revertible.
+- Roll back only to the last commit that passed gate.
+- Record rollback cause and follow-up plan.
+
+## Done Criteria
+- Issue has an approved recovery path and documented rationale.
+
+## Anti-patterns
+- Blindly retrying same failing strategy
+- Silent rollback without traceability
+- Continuing without user alignment

package/assets/skills/session-logging/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: session-logging
+description: "Accurate, auditable execution journal for each working session."
+---
+# Session Logging Skill
+
+## Purpose
+Maintain an accurate, auditable execution journal for each working session.
+
+## Use when
+- Starting/ending a session
+- Completing issues/milestones
+- Syncing GitHub status
+
+## Required File
+`sessions-<ISO-date>.md`
+
+## Required Sections
+- Status (milestone states)
+- Work Completed (`[mX/iY]` references)
+- Completion Gate Passed (include ✅ and consecutive-pass evidence)
+- Decisions Made
+- Blockers
+- GitHub Sync (created/closed/updated issue IDs)
+- Branch
+- Date (ISO timestamp)
+
+## Procedure
+1. Create/update the session file at session start and after meaningful milestones.
+2. Keep entries factual and aligned with plan/GitHub state.
+3. Record gate-pass evidence per completed issue.
+
+## Done Criteria
+- Session file reflects real progress and traceable references.
+
+## Anti-patterns
+- Retroactive guesswork
+- Missing gate evidence
+- Inconsistent milestone/issue IDs