fix(plugin): revert default to 3456 + correct v3.16.1 narrative; v3.16.2

v3.16.1's narrative ("OCP server moved to 3478 default in v3.14+") was
incorrect. OCP source default has been 3456 since 593d0dc (initial
release) and never changed. The single observation of 3478 is the
maintainer's Mac mini, whose plist was rewritten with --port 3478
during a 2026-05-08 PR #71 dogfood smoke-test accident (see
~/.cc-rules/memory/learnings/subagent_setup_mjs_prod_host_collision.md).
The drift was never reconciled and v3.16.1 mistakenly canonised the
post-accident port as the new default.

This release reverts:
- ocp-plugin/index.js fallback → http://127.0.0.1:3456
- openclaw.plugin.json configSchema.proxyUrl.default → http://127.0.0.1:3456
- README §Environment Variables CLAUDE_PROXY_PORT default → 3456
- top-level package.json → 3.16.2

PR #95's env-reading path (OCP_PROXY_URL → CLAUDE_PROXY_PORT → fallback)
is preserved — that part was good design and stays. Only the hardcoded
fallback default changes.

Hosts whose OCP plist injects a non-default port must also inject the
same CLAUDE_PROXY_PORT into the OpenClaw plist for the plugin to follow
(documented in the new index.js comment block).

Mac mini's plist was reverted from 3478 to 3456 as part of this deploy
(per-host correction; no source code reflects host-specific state).

CHANGELOG includes an explicit erratum entry under v3.16.1 marking it
superseded.

Process note: this PR was triggered by maintainer asking "why was the
port changed?" — the answer revealed I (PM) wrote v3.16.1's CHANGELOG
without running `git log -G "3478" -- setup.mjs`. Iron Rule 2
(evidence-first) was violated. Future commits asserting historical
facts must include the grep that confirmed them.

No cli.js citation needed: OCP-internal plugin + docs, no server.mjs
change.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.claude/skills/speckit-analyze/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: speckit-analyze
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
+argument-hint: "Optional focus areas for analysis"
+user-invocable: true
+disable-model-invocation: false
+compatibility: "Requires spec-kit project structure with .specify/ directory"
+metadata:
+  author: github-spec-kit
+  source: claude:templates/commands/analyze.md
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before analysis)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_analyze` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` -> `/speckit-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    Wait for the result of the hook command before proceeding to the Goal.
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/speckit.tasks` has successfully produced a complete `tasks.md`.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
+
+**Constitution Authority**: The project constitution (`/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.analyze`.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+Run `{SCRIPT}` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
+
+- SPEC = FEATURE_DIR/spec.md
+- PLAN = FEATURE_DIR/plan.md
+- TASKS = FEATURE_DIR/tasks.md
+
+Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only the minimal necessary context from each artifact:
+
+**From spec.md:**
+
+- Overview/Context
+- Functional Requirements
+- Success Criteria (measurable outcomes — e.g., performance, security, availability, user success, business impact)
+- User Stories
+- Edge Cases (if present)
+
+**From plan.md:**
+
+- Architecture/stack choices
+- Data Model references
+- Phases
+- Technical constraints
+
+**From tasks.md:**
+
+- Task IDs
+- Descriptions
+- Phase grouping
+- Parallel markers [P]
+- Referenced file paths
+
+**From constitution:**
+
+- Load `/memory/constitution.md` for principle validation
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: For each Functional Requirement (FR-###) and Success Criterion (SC-###), record a stable key. Use the explicit FR-/SC- identifier as the primary key when present, and optionally also derive an imperative-phrase slug for readability (e.g., "User can upload file" → `user-can-upload-file`). Include only Success Criteria items that require buildable work (e.g., load-testing infrastructure, security audit tooling), and exclude post-launch outcome metrics and business KPIs (e.g., "Reduce support tickets by 50%").
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Duplication Detection
+
+- Identify near-duplicate requirements
+- Mark lower-quality phrasing for consolidation
+
+#### B. Ambiguity Detection
+
+- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
+
+#### C. Underspecification
+
+- Requirements with verbs but missing object or measurable outcome
+- User stories missing acceptance criteria alignment
+- Tasks referencing files or components not defined in spec/plan
+
+#### D. Constitution Alignment
+
+- Any requirement or plan element conflicting with a MUST principle
+- Missing mandated sections or quality gates from constitution
+
+#### E. Coverage Gaps
+
+- Requirements with zero associated tasks
+- Tasks with no mapped requirement/story
+- Success Criteria requiring buildable work (performance, security, availability) not reflected in tasks
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+
+### 6. Produce Compact Analysis Report
+
+Output a Markdown report (no file writes) with the following structure:
+
+## Specification Analysis Report
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+
+(Add one row per finding; generate stable IDs prefixed by category initial.)
+
+**Coverage Summary Table:**
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|-----------------|-----------|----------|-------|
+
+**Constitution Alignment Issues:** (if any)
+
+**Unmapped Tasks:** (if any)
+
+**Metrics:**
+
+- Total Requirements
+- Total Tasks
+- Coverage % (requirements with >=1 task)
+- Ambiguity Count
+- Duplication Count
+- Critical Issues Count
+
+### 7. Provide Next Actions
+
+At end of report, output a concise Next Actions block:
+
+- If CRITICAL issues exist: Recommend resolving before `/speckit.implement`
+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
+- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
+
+### 8. Offer Remediation
+
+Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
+
+### 9. Check for extension hooks
+
+After reporting, check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.after_analyze` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` -> `/speckit-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+
+### Analysis Guidelines
+
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+
+## Context
+
+{ARGS}

.claude/skills/speckit-checklist/SKILL.md

@@ -0,0 +1,371 @@
+---
+name: speckit-checklist
+description: Generate a custom checklist for the current feature based on user requirements.
+argument-hint: "Domain or focus area for the checklist"
+user-invocable: true
+disable-model-invocation: false
+compatibility: "Requires spec-kit project structure with .specify/ directory"
+metadata:
+  author: github-spec-kit
+  source: claude:templates/commands/checklist.md
+---
+
+## Checklist Purpose: "Unit Tests for English"
+
+**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain.
+
+**NOT for verification/testing**:
+
+- ❌ NOT "Verify the button clicks correctly"
+- ❌ NOT "Test error handling works"
+- ❌ NOT "Confirm the API returns 200"
+- ❌ NOT checking if code/implementation matches the spec
+
+**FOR requirements quality validation**:
+
+- ✅ "Are visual hierarchy requirements defined for all card types?" (completeness)
+- ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity)
+- ✅ "Are hover state requirements consistent across all interactive elements?" (consistency)
+- ✅ "Are accessibility requirements defined for keyboard navigation?" (coverage)
+- ✅ "Does the spec define what happens when logo image fails to load?" (edge cases)
+
+**Metaphor**: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before checklist generation)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_checklist` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` -> `/speckit-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    Wait for the result of the hook command before proceeding to the Execution Steps.
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Execution Steps
+
+1. **Setup**: Run `{SCRIPT}` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list.
+   - All file paths must be absolute.
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST:
+   - Be generated from the user's phrasing + extracted signals from spec/plan/tasks
+   - Only ask about information that materially changes checklist content
+   - Be skipped individually if already unambiguous in `$ARGUMENTS`
+   - Prefer precision over breadth
+
+   Generation algorithm:
+   1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts").
+   2. Cluster signals into candidate focus areas (max 4) ranked by relevance.
+   3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit.
+   4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria.
+   5. Formulate questions chosen from these archetypes:
+      - Scope refinement (e.g., "Should this include integration touchpoints with X and Y or stay limited to local module correctness?")
+      - Risk prioritization (e.g., "Which of these potential risk areas should receive mandatory gating checks?")
+      - Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal release gate?")
+      - Audience framing (e.g., "Will this be used by the author only or peers during PR review?")
+      - Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items this round?")
+      - Scenario class gap (e.g., "No recovery flows detected—are rollback / partial failure paths in scope?")
+
+   Question formatting rules:
+   - If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters
+   - Limit to A–E options maximum; omit table if a free-form answer is clearer
+   - Never ask the user to restate what they already said
+   - Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope."
+
+   Defaults when interaction impossible:
+   - Depth: Standard
+   - Audience: Reviewer (PR) if code-related; Author otherwise
+   - Focus: Top 2 relevance clusters
+
+   Output the questions (label Q1/Q2/Q3). After answers: if ≥2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow‑ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more.
+
+3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers:
+   - Derive checklist theme (e.g., security, review, deploy, ux)
+   - Consolidate explicit must-have items mentioned by user
+   - Map focus selections to category scaffolding
+   - Infer any missing context from spec/plan/tasks (do NOT hallucinate)
+
+4. **Load feature context**: Read from FEATURE_DIR:
+   - spec.md: Feature requirements and scope
+   - plan.md (if exists): Technical details, dependencies
+   - tasks.md (if exists): Implementation tasks
+
+   **Context Loading Strategy**:
+   - Load only necessary portions relevant to active focus areas (avoid full-file dumping)
+   - Prefer summarizing long sections into concise scenario/requirement bullets
+   - Use progressive disclosure: add follow-on retrieval only if gaps detected
+   - If source docs are large, generate interim summary items instead of embedding raw text
+
+5. **Generate checklist** - Create "Unit Tests for Requirements":
+   - Create `FEATURE_DIR/checklists/` directory if it doesn't exist
+   - Generate unique checklist filename:
+     - Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`)
+     - Format: `[domain].md`
+   - File handling behavior:
+     - If file does NOT exist: Create new file and number items starting from CHK001
+     - If file exists: Append new items to existing file, continuing from the last CHK ID (e.g., if last item is CHK015, start new items at CHK016)
+   - Never delete or replace existing checklist content - always preserve and append
+
+   **CORE PRINCIPLE - Test the Requirements, Not the Implementation**:
+   Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for:
+   - **Completeness**: Are all necessary requirements present?
+   - **Clarity**: Are requirements unambiguous and specific?
+   - **Consistency**: Do requirements align with each other?
+   - **Measurability**: Can requirements be objectively verified?
+   - **Coverage**: Are all scenarios/edge cases addressed?
+
+   **Category Structure** - Group items by requirement quality dimensions:
+   - **Requirement Completeness** (Are all necessary requirements documented?)
+   - **Requirement Clarity** (Are requirements specific and unambiguous?)
+   - **Requirement Consistency** (Do requirements align without conflicts?)
+   - **Acceptance Criteria Quality** (Are success criteria measurable?)
+   - **Scenario Coverage** (Are all flows/cases addressed?)
+   - **Edge Case Coverage** (Are boundary conditions defined?)
+   - **Non-Functional Requirements** (Performance, Security, Accessibility, etc. - are they specified?)
+   - **Dependencies & Assumptions** (Are they documented and validated?)
+   - **Ambiguities & Conflicts** (What needs clarification?)
+
+   **HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English"**:
+
+   ❌ **WRONG** (Testing implementation):
+   - "Verify landing page displays 3 episode cards"
+   - "Test hover states work on desktop"
+   - "Confirm logo click navigates home"
+
+   ✅ **CORRECT** (Testing requirements quality):
+   - "Are the exact number and layout of featured episodes specified?" [Completeness]
+   - "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity]
+   - "Are hover state requirements consistent across all interactive elements?" [Consistency]
+   - "Are keyboard navigation requirements defined for all interactive UI?" [Coverage]
+   - "Is the fallback behavior specified when logo image fails to load?" [Edge Cases]
+   - "Are loading states defined for asynchronous episode data?" [Completeness]
+   - "Does the spec define visual hierarchy for competing UI elements?" [Clarity]
+
+   **ITEM STRUCTURE**:
+   Each item should follow this pattern:
+   - Question format asking about requirement quality
+   - Focus on what's WRITTEN (or not written) in the spec/plan
+   - Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.]
+   - Reference spec section `[Spec §X.Y]` when checking existing requirements
+   - Use `[Gap]` marker when checking for missing requirements
+
+   **EXAMPLES BY QUALITY DIMENSION**:
+
+   Completeness:
+   - "Are error handling requirements defined for all API failure modes? [Gap]"
+   - "Are accessibility requirements specified for all interactive elements? [Completeness]"
+   - "Are mobile breakpoint requirements defined for responsive layouts? [Gap]"
+
+   Clarity:
+   - "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]"
+   - "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]"
+   - "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]"
+
+   Consistency:
+   - "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]"
+   - "Are card component requirements consistent between landing and detail pages? [Consistency]"
+
+   Coverage:
+   - "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]"
+   - "Are concurrent user interaction scenarios addressed? [Coverage, Gap]"
+   - "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]"
+
+   Measurability:
+   - "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]"
+   - "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]"
+
+   **Scenario Classification & Coverage** (Requirements Quality Focus):
+   - Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios
+   - For each scenario class, ask: "Are [scenario type] requirements complete, clear, and consistent?"
+   - If scenario class missing: "Are [scenario type] requirements intentionally excluded or missing? [Gap]"
+   - Include resilience/rollback when state mutation occurs: "Are rollback requirements defined for migration failures? [Gap]"
+
+   **Traceability Requirements**:
+   - MINIMUM: ≥80% of items MUST include at least one traceability reference
+   - Each item should reference: spec section `[Spec §X.Y]`, or use markers: `[Gap]`, `[Ambiguity]`, `[Conflict]`, `[Assumption]`
+   - If no ID system exists: "Is a requirement & acceptance criteria ID scheme established? [Traceability]"
+
+   **Surface & Resolve Issues** (Requirements Quality Problems):
+   Ask questions about the requirements themselves:
+   - Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]"
+   - Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]"
+   - Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]"
+   - Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]"
+   - Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]"
+
+   **Content Consolidation**:
+   - Soft cap: If raw candidate items > 40, prioritize by risk/impact
+   - Merge near-duplicates checking the same requirement aspect
+   - If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]"
+
+   **🚫 ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test:
+   - ❌ Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior
+   - ❌ References to code execution, user actions, system behavior
+   - ❌ "Displays correctly", "works properly", "functions as expected"
+   - ❌ "Click", "navigate", "render", "load", "execute"
+   - ❌ Test cases, test plans, QA procedures
+   - ❌ Implementation details (frameworks, APIs, algorithms)
+
+   **✅ REQUIRED PATTERNS** - These test requirements quality:
+   - ✅ "Are [requirement type] defined/specified/documented for [scenario]?"
+   - ✅ "Is [vague term] quantified/clarified with specific criteria?"
+   - ✅ "Are requirements consistent between [section A] and [section B]?"
+   - ✅ "Can [requirement] be objectively measured/verified?"
+   - ✅ "Are [edge cases/scenarios] addressed in requirements?"
+   - ✅ "Does the spec define [missing aspect]?"
+
+6. **Structure Reference**: Generate the checklist following the canonical template in `templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### <requirement item>` lines with globally incrementing IDs starting at CHK001.
+
+7. **Report**: Output full path to checklist file, item count, and summarize whether the run created a new file or appended to an existing one. Summarize:
+   - Focus areas selected
+   - Depth level
+   - Actor/timing
+   - Any explicit user-specified must-have items incorporated
+
+**Important**: Each `/speckit.checklist` command invocation uses a short, descriptive checklist filename and either creates a new file or appends to an existing one. This allows:
+
+- Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`)
+- Simple, memorable filenames that indicate checklist purpose
+- Easy identification and navigation in the `checklists/` folder
+
+To avoid clutter, use descriptive types and clean up obsolete checklists when done.
+
+## Example Checklist Types & Sample Items
+
+**UX Requirements Quality:** `ux.md`
+
+Sample items (testing the requirements, NOT the implementation):
+
+- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]"
+- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]"
+- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]"
+- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]"
+- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]"
+- "Can 'prominent display' be objectively measured? [Measurability, Spec §FR-4]"
+
+**API Requirements Quality:** `api.md`
+
+Sample items:
+
+- "Are error response formats specified for all failure scenarios? [Completeness]"
+- "Are rate limiting requirements quantified with specific thresholds? [Clarity]"
+- "Are authentication requirements consistent across all endpoints? [Consistency]"
+- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]"
+- "Is versioning strategy documented in requirements? [Gap]"
+
+**Performance Requirements Quality:** `performance.md`
+
+Sample items:
+
+- "Are performance requirements quantified with specific metrics? [Clarity]"
+- "Are performance targets defined for all critical user journeys? [Coverage]"
+- "Are performance requirements under different load conditions specified? [Completeness]"
+- "Can performance requirements be objectively measured? [Measurability]"
+- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]"
+
+**Security Requirements Quality:** `security.md`
+
+Sample items:
+
+- "Are authentication requirements specified for all protected resources? [Coverage]"
+- "Are data protection requirements defined for sensitive information? [Completeness]"
+- "Is the threat model documented and requirements aligned to it? [Traceability]"
+- "Are security requirements consistent with compliance obligations? [Consistency]"
+- "Are security failure/breach response requirements defined? [Gap, Exception Flow]"
+
+## Anti-Examples: What NOT To Do
+
+**❌ WRONG - These test implementation, not requirements:**
+
+```markdown
+- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001]
+- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003]
+- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010]
+- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005]
+```
+
+**✅ CORRECT - These test requirements quality:**
+
+```markdown
+- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001]
+- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003]
+- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010]
+- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005]
+- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap]
+- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001]
+```
+
+**Key Differences:**
+
+- Wrong: Tests if the system works correctly
+- Correct: Tests if the requirements are written correctly
+- Wrong: Verification of behavior
+- Correct: Validation of requirement quality
+- Wrong: "Does it do X?"
+- Correct: "Is X clearly specified?"
+
+## Post-Execution Checks
+
+**Check for extension hooks (after checklist generation)**:
+Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.after_checklist` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` -> `/speckit-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently

.claude/skills/speckit-clarify/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: speckit-clarify
+description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
+argument-hint: "Optional areas to clarify in the spec"
+user-invocable: true
+disable-model-invocation: false
+compatibility: "Requires spec-kit project structure with .specify/ directory"
+metadata:
+  author: github-spec-kit
+  source: claude:templates/commands/clarify.md
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before clarification)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_clarify` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` -> `/speckit-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    Wait for the result of the hook command before proceeding to the Outline.
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Outline
+
+Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.
+
+Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/speckit.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.
+
+Execution steps:
+
+1. Run `{SCRIPT}` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields:
+   - `FEATURE_DIR`
+   - `FEATURE_SPEC`
+   - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.)
+   - If JSON parsing fails, abort and instruct user to re-run `/speckit.specify` or verify feature branch environment.
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).
+
+   Functional Scope & Behavior:
+   - Core user goals & success criteria
+   - Explicit out-of-scope declarations
+   - User roles / personas differentiation
+
+   Domain & Data Model:
+   - Entities, attributes, relationships
+   - Identity & uniqueness rules
+   - Lifecycle/state transitions
+   - Data volume / scale assumptions
+
+   Interaction & UX Flow:
+   - Critical user journeys / sequences
+   - Error/empty/loading states
+   - Accessibility or localization notes
+
+   Non-Functional Quality Attributes:
+   - Performance (latency, throughput targets)
+   - Scalability (horizontal/vertical, limits)
+   - Reliability & availability (uptime, recovery expectations)
+   - Observability (logging, metrics, tracing signals)
+   - Security & privacy (authN/Z, data protection, threat assumptions)
+   - Compliance / regulatory constraints (if any)
+
+   Integration & External Dependencies:
+   - External services/APIs and failure modes
+   - Data import/export formats
+   - Protocol/versioning assumptions
+
+   Edge Cases & Failure Handling:
+   - Negative scenarios
+   - Rate limiting / throttling
+   - Conflict resolution (e.g., concurrent edits)
+
+   Constraints & Tradeoffs:
+   - Technical constraints (language, storage, hosting)
+   - Explicit tradeoffs or rejected alternatives
+
+   Terminology & Consistency:
+   - Canonical glossary terms
+   - Avoided synonyms / deprecated terms
+
+   Completion Signals:
+   - Acceptance criteria testability
+   - Measurable Definition of Done style indicators
+
+   Misc / Placeholders:
+   - TODO markers / unresolved decisions
+   - Ambiguous adjectives ("robust", "intuitive") lacking quantification
+
+   For each category with Partial or Missing status, add a candidate question opportunity unless:
+   - Clarification would not materially change implementation or validation strategy
+   - Information is better deferred to planning phase (note internally)
+
+3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
+    - Maximum of 5 total questions across the whole session.
+    - Each question must be answerable with EITHER:
+       - A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
+       - A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
+    - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
+    - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
+    - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
+    - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
+    - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.
+
+4. Sequential questioning loop (interactive):
+    - Present EXACTLY ONE question at a time.
+    - For multiple‑choice questions:
+       - **Analyze all options** and determine the **most suitable option** based on:
+          - Best practices for the project type
+          - Common patterns in similar implementations
+          - Risk reduction (security, performance, maintainability)
+          - Alignment with any explicit project goals or constraints visible in the spec
+       - Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice).
+       - Format as: `**Recommended:** Option [X] - <reasoning>`
+       - Then render all options as a Markdown table:
+
+       | Option | Description |
+       |--------|-------------|
+       | A | <Option A description> |
+       | B | <Option B description> |
+       | C | <Option C description> (add D/E as needed up to 5) |
+       | Short | Provide a different short answer (<=5 words) (Include only if free-form alternative is appropriate) |
+
+       - After the table, add: `You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.`
+    - For short‑answer style (no meaningful discrete options):
+       - Provide your **suggested answer** based on best practices and context.
+       - Format as: `**Suggested:** <your proposed answer> - <brief reasoning>`
+       - Then output: `Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.`
+    - After the user answers:
+       - If the user replies with "yes", "recommended", or "suggested", use your previously stated recommendation/suggestion as the answer.
+       - Otherwise, validate the answer maps to one option or fits the <=5 word constraint.
+       - If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
+       - Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.
+    - Stop asking further questions when:
+       - All critical ambiguities resolved early (remaining queued items become unnecessary), OR
+       - User signals completion ("done", "good", "no more"), OR
+       - You reach 5 asked questions.
+    - Never reveal future queued questions in advance.
+    - If no valid questions exist at start, immediately report no critical ambiguities.
+
+5. Integration after EACH accepted answer (incremental update approach):
+    - Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
+    - For the first integrated answer in this session:
+       - Ensure a `## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
+       - Under it, create (if not present) a `### Session YYYY-MM-DD` subheading for today.
+    - Append a bullet line immediately after acceptance: `- Q: <question> → A: <final answer>`.
+    - Then immediately apply the clarification to the most appropriate section(s):
+       - Functional ambiguity → Update or add a bullet in Functional Requirements.
+       - User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
+       - Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
+       - Non-functional constraint → Add/modify measurable criteria in Success Criteria > Measurable Outcomes (convert vague adjective to metric or explicit target).
+       - Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
+       - Terminology conflict → Normalize term across spec; retain original only if necessary by adding `(formerly referred to as "X")` once.
+    - If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
+    - Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
+    - Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
+    - Keep each inserted clarification minimal and testable (avoid narrative drift).
+
+6. Validation (performed after EACH write plus final pass):
+   - Clarifications session contains exactly one bullet per accepted answer (no duplicates).
+   - Total asked (accepted) questions ≤ 5.
+   - Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
+   - No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
+   - Markdown structure valid; only allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD`.
+   - Terminology consistency: same canonical term used across all updated sections.
+
+7. Write the updated spec back to `FEATURE_SPEC`.
+
+8. Report completion (after questioning loop ends or early termination):
+   - Number of questions asked & answered.
+   - Path to updated spec.
+   - Sections touched (list names).
+   - Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
+   - If any Outstanding or Deferred remain, recommend whether to proceed to `/speckit.plan` or run `/speckit.clarify` again later post-plan.
+   - Suggested next command.
+
+Behavior rules:
+
+- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
+- If spec file missing, instruct user to run `/speckit.specify` first (do not create a new spec here).
+- Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
+- Avoid speculative tech stack questions unless the absence blocks functional clarity.
+- Respect user early termination signals ("stop", "done", "proceed").
+- If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
+- If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.
+
+Context for prioritization: {ARGS}
+
+## Post-Execution Checks
+
+**Check for extension hooks (after clarification)**:
+Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.after_clarify` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` -> `/speckit-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently

.claude/skills/speckit-constitution/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: speckit-constitution
+description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.
+argument-hint: "Principles or values for the project constitution"
+user-invocable: true
+disable-model-invocation: false
+compatibility: "Requires spec-kit project structure with .specify/ directory"
+metadata:
+  author: github-spec-kit
+  source: claude:templates/commands/constitution.md
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before constitution update)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_constitution` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` -> `/speckit-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    Wait for the result of the hook command before proceeding to the Outline.
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Outline
+
+You are updating the project constitution at `.specify/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
+
+**Note**: If `.specify/memory/constitution.md` does not exist yet, it should have been initialized from `.specify/templates/constitution-template.md` during project setup. If it's missing, copy the template first.
+
+Follow this execution flow:
+
+1. Load the existing constitution at `.specify/memory/constitution.md`.
+   - Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
+   **IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.
+
+2. Collect/derive values for placeholders:
+   - If user input (conversation) supplies a value, use it.
+   - Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded).
+   - For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous.
+   - `CONSTITUTION_VERSION` must increment according to semantic versioning rules:
+     - MAJOR: Backward incompatible governance/principle removals or redefinitions.
+     - MINOR: New principle/section added or materially expanded guidance.
+     - PATCH: Clarifications, wording, typo fixes, non-semantic refinements.
+   - If version bump type ambiguous, propose reasoning before finalizing.
+
+3. Draft the updated constitution content:
+   - Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left).
+   - Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance.
+   - Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious.
+   - Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.
+
+4. Consistency propagation checklist (convert prior checklist into active validations):
+   - Read `.specify/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
+   - Read `.specify/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
+   - Read `.specify/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
+   - Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
+   - Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed.
+
+5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
+   - Version change: old → new
+   - List of modified principles (old title → new title if renamed)
+   - Added sections
+   - Removed sections
+   - Templates requiring updates (✅ updated / ⚠ pending) with file paths
+   - Follow-up TODOs if any placeholders intentionally deferred.
+
+6. Validation before final output:
+   - No remaining unexplained bracket tokens.
+   - Version line matches report.
+   - Dates ISO format YYYY-MM-DD.
+   - Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).
+
+7. Write the completed constitution back to `.specify/memory/constitution.md` (overwrite).
+
+8. Output a final summary to the user with:
+   - New version and bump rationale.
+   - Any files flagged for manual follow-up.
+   - Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`).
+
+Formatting & Style Requirements:
+
+- Use Markdown headings exactly as in the template (do not demote/promote levels).
+- Wrap long rationale lines to keep readability (<100 chars ideally) but do not hard enforce with awkward breaks.
+- Keep a single blank line between sections.
+- Avoid trailing whitespace.
+
+If the user supplies partial updates (e.g., only one principle revision), still perform validation and version decision steps.
+
+If critical info missing (e.g., ratification date truly unknown), insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report under deferred items.
+
+Do not create a new template; always operate on the existing `.specify/memory/constitution.md` file.
+
+## Post-Execution Checks
+
+**Check for extension hooks (after constitution update)**:
+Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.after_constitution` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` -> `/speckit-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently

.claude/skills/speckit-implement/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: speckit-implement
+description: Execute the implementation plan by processing and executing all tasks defined in tasks.md
+argument-hint: "Optional implementation guidance or task filter"
+user-invocable: true
+disable-model-invocation: false
+compatibility: "Requires spec-kit project structure with .specify/ directory"
+metadata:
+  author: github-spec-kit
+  source: claude:templates/commands/implement.md
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before implementation)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_implement` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` -> `/speckit-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+    
+    Wait for the result of the hook command before proceeding to the Outline.
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Outline
+
+1. Run `{SCRIPT}` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Check checklists status** (if FEATURE_DIR/checklists/ exists):
+   - Scan all checklist files in the checklists/ directory
+   - For each checklist, count:
+     - Total items: All lines matching `- [ ]` or `- [X]` or `- [x]`
+     - Completed items: Lines matching `- [X]` or `- [x]`
+     - Incomplete items: Lines matching `- [ ]`
+   - Create a status table:
+
+     ```text
+     | Checklist | Total | Completed | Incomplete | Status |
+     |-----------|-------|-----------|------------|--------|
+     | ux.md     | 12    | 12        | 0          | ✓ PASS |
+     | test.md   | 8     | 5         | 3          | ✗ FAIL |
+     | security.md | 6   | 6         | 0          | ✓ PASS |
+     ```
+
+   - Calculate overall status:
+     - **PASS**: All checklists have 0 incomplete items
+     - **FAIL**: One or more checklists have incomplete items
+
+   - **If any checklist is incomplete**:
+     - Display the table with incomplete item counts
+     - **STOP** and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)"
+     - Wait for user response before continuing
+     - If user says "no" or "wait" or "stop", halt execution
+     - If user says "yes" or "proceed" or "continue", proceed to step 3
+
+   - **If all checklists are complete**:
+     - Display the table showing all checklists passed
+     - Automatically proceed to step 3
+
+3. Load and analyze the implementation context:
+   - **REQUIRED**: Read tasks.md for the complete task list and execution plan
+   - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure
+   - **IF EXISTS**: Read data-model.md for entities and relationships
+   - **IF EXISTS**: Read contracts/ for API specifications and test requirements
+   - **IF EXISTS**: Read research.md for technical decisions and constraints
+   - **IF EXISTS**: Read quickstart.md for integration scenarios
+
+4. **Project Setup Verification**:
+   - **REQUIRED**: Create/verify ignore files based on actual project setup:
+
+   **Detection & Creation Logic**:
+   - Check if the following command succeeds to determine if the repository is a git repo (create/verify .gitignore if so):
+
+     ```sh
+     git rev-parse --git-dir 2>/dev/null
+     ```
+
+   - Check if Dockerfile* exists or Docker in plan.md → create/verify .dockerignore
+   - Check if .eslintrc* exists → create/verify .eslintignore
+   - Check if eslint.config.* exists → ensure the config's `ignores` entries cover required patterns
+   - Check if .prettierrc* exists → create/verify .prettierignore
+   - Check if .npmrc or package.json exists → create/verify .npmignore (if publishing)
+   - Check if terraform files (*.tf) exist → create/verify .terraformignore
+   - Check if .helmignore needed (helm charts present) → create/verify .helmignore
+
+   **If ignore file already exists**: Verify it contains essential patterns, append missing critical patterns only
+   **If ignore file missing**: Create with full pattern set for detected technology
+
+   **Common Patterns by Technology** (from plan.md tech stack):
+   - **Node.js/JavaScript/TypeScript**: `node_modules/`, `dist/`, `build/`, `*.log`, `.env*`
+   - **Python**: `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `dist/`, `*.egg-info/`
+   - **Java**: `target/`, `*.class`, `*.jar`, `.gradle/`, `build/`
+   - **C#/.NET**: `bin/`, `obj/`, `*.user`, `*.suo`, `packages/`
+   - **Go**: `*.exe`, `*.test`, `vendor/`, `*.out`
+   - **Ruby**: `.bundle/`, `log/`, `tmp/`, `*.gem`, `vendor/bundle/`
+   - **PHP**: `vendor/`, `*.log`, `*.cache`, `*.env`
+   - **Rust**: `target/`, `debug/`, `release/`, `*.rs.bk`, `*.rlib`, `*.prof*`, `.idea/`, `*.log`, `.env*`
+   - **Kotlin**: `build/`, `out/`, `.gradle/`, `.idea/`, `*.class`, `*.jar`, `*.iml`, `*.log`, `.env*`
+   - **C++**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.so`, `*.a`, `*.exe`, `*.dll`, `.idea/`, `*.log`, `.env*`
+   - **C**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.a`, `*.so`, `*.exe`, `*.dll`, `autom4te.cache/`, `config.status`, `config.log`, `.idea/`, `*.log`, `.env*`
+   - **Swift**: `.build/`, `DerivedData/`, `*.swiftpm/`, `Packages/`
+   - **R**: `.Rproj.user/`, `.Rhistory`, `.RData`, `.Ruserdata`, `*.Rproj`, `packrat/`, `renv/`
+   - **Universal**: `.DS_Store`, `Thumbs.db`, `*.tmp`, `*.swp`, `.vscode/`, `.idea/`
+
+   **Tool-Specific Patterns**:
+   - **Docker**: `node_modules/`, `.git/`, `Dockerfile*`, `.dockerignore`, `*.log*`, `.env*`, `coverage/`
+   - **ESLint**: `node_modules/`, `dist/`, `build/`, `coverage/`, `*.min.js`
+   - **Prettier**: `node_modules/`, `dist/`, `build/`, `coverage/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
+   - **Terraform**: `.terraform/`, `*.tfstate*`, `*.tfvars`, `.terraform.lock.hcl`
+   - **Kubernetes/k8s**: `*.secret.yaml`, `secrets/`, `.kube/`, `kubeconfig*`, `*.key`, `*.crt`
+
+5. Parse tasks.md structure and extract:
+   - **Task phases**: Setup, Tests, Core, Integration, Polish
+   - **Task dependencies**: Sequential vs parallel execution rules
+   - **Task details**: ID, description, file paths, parallel markers [P]
+   - **Execution flow**: Order and dependency requirements
+
+6. Execute implementation following the task plan:
+   - **Phase-by-phase execution**: Complete each phase before moving to the next
+   - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together  
+   - **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
+   - **File-based coordination**: Tasks affecting the same files must run sequentially
+   - **Validation checkpoints**: Verify each phase completion before proceeding
+
+7. Implementation execution rules:
+   - **Setup first**: Initialize project structure, dependencies, configuration
+   - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
+   - **Core development**: Implement models, services, CLI commands, endpoints
+   - **Integration work**: Database connections, middleware, logging, external services
+   - **Polish and validation**: Unit tests, performance optimization, documentation
+
+8. Progress tracking and error handling:
+   - Report progress after each completed task
+   - Halt execution if any non-parallel task fails
+   - For parallel tasks [P], continue with successful tasks, report failed ones
+   - Provide clear error messages with context for debugging
+   - Suggest next steps if implementation cannot proceed
+   - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.
+
+9. Completion validation:
+   - Verify all required tasks are completed
+   - Check that implemented features match the original specification
+   - Validate that tests pass and coverage meets requirements
+   - Confirm the implementation follows the technical plan
+   - Report final status with summary of completed work
+
+Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/speckit.tasks` first to regenerate the task list.
+
+10. **Check for extension hooks**: After completion validation, check if `.specify/extensions.yml` exists in the project root.
+    - If it exists, read it and look for entries under the `hooks.after_implement` key
+    - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+    - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+    - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+      - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+      - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+    - When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` -> `/speckit-git-commit`.
+    - For each executable hook, output the following based on its `optional` flag:
+      - **Optional hook** (`optional: true`):
+        ```
+        ## Extension Hooks
+
+        **Optional Hook**: {extension}
+        Command: `/{command}`
+        Description: {description}
+
+        Prompt: {prompt}
+        To execute: `/{command}`
+        ```
+      - **Mandatory hook** (`optional: false`):
+        ```
+        ## Extension Hooks
+
+        **Automatic Hook**: {extension}
+        Executing: `/{command}`
+        EXECUTE_COMMAND: {command}
+        ```
+    - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently

.claude/skills/speckit-plan/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: speckit-plan
+description: Execute the implementation planning workflow using the plan template to generate design artifacts.
+argument-hint: "Optional guidance for the planning phase"
+user-invocable: true
+disable-model-invocation: false
+compatibility: "Requires spec-kit project structure with .specify/ directory"
+metadata:
+  author: github-spec-kit
+  source: claude:templates/commands/plan.md
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before planning)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_plan` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` -> `/speckit-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    Wait for the result of the hook command before proceeding to the Outline.
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Outline
+
+1. **Setup**: Run `{SCRIPT}` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load context**: Read FEATURE_SPEC and `/memory/constitution.md`. Load IMPL_PLAN template (already copied).
+
+3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
+   - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
+   - Fill Constitution Check section from constitution
+   - Evaluate gates (ERROR if violations unjustified)
+   - Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
+   - Phase 1: Generate data-model.md, contracts/, quickstart.md
+   - Phase 1: Update agent context by running the agent script
+   - Re-evaluate Constitution Check post-design
+
+4. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
+
+5. **Check for extension hooks**: After reporting, check if `.specify/extensions.yml` exists in the project root.
+   - If it exists, read it and look for entries under the `hooks.after_plan` key
+   - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+   - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+   - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+     - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+     - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+   - When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` -> `/speckit-git-commit`.
+   - For each executable hook, output the following based on its `optional` flag:
+     - **Optional hook** (`optional: true`):
+       ```
+       ## Extension Hooks
+
+       **Optional Hook**: {extension}
+       Command: `/{command}`
+       Description: {description}
+
+       Prompt: {prompt}
+       To execute: `/{command}`
+       ```
+     - **Mandatory hook** (`optional: false`):
+       ```
+       ## Extension Hooks
+
+       **Automatic Hook**: {extension}
+       Executing: `/{command}`
+       EXECUTE_COMMAND: {command}
+       ```
+   - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Phases
+
+### Phase 0: Outline & Research
+
+1. **Extract unknowns from Technical Context** above:
+   - For each NEEDS CLARIFICATION → research task
+   - For each dependency → best practices task
+   - For each integration → patterns task
+
+2. **Generate and dispatch research agents**:
+
+   ```text
+   For each unknown in Technical Context:
+     Task: "Research {unknown} for {feature context}"
+   For each technology choice:
+     Task: "Find best practices for {tech} in {domain}"
+   ```
+
+3. **Consolidate findings** in `research.md` using format:
+   - Decision: [what was chosen]
+   - Rationale: [why chosen]
+   - Alternatives considered: [what else evaluated]
+
+**Output**: research.md with all NEEDS CLARIFICATION resolved
+
+### Phase 1: Design & Contracts
+
+**Prerequisites:** `research.md` complete
+
+1. **Extract entities from feature spec** → `data-model.md`:
+   - Entity name, fields, relationships
+   - Validation rules from requirements
+   - State transitions if applicable
+
+2. **Define interface contracts** (if project has external interfaces) → `/contracts/`:
+   - Identify what interfaces the project exposes to users or other systems
+   - Document the contract format appropriate for the project type
+   - Examples: public APIs for libraries, command schemas for CLI tools, endpoints for web services, grammars for parsers, UI contracts for applications
+   - Skip if project is purely internal (build scripts, one-off tools, etc.)
+
+3. **Agent context update**:
+   - Update the plan reference between the `<!-- SPECKIT START -->` and `<!-- SPECKIT END -->` markers in `__CONTEXT_FILE__` to point to the plan file created in step 1 (the IMPL_PLAN path)
+
+**Output**: data-model.md, /contracts/*, quickstart.md, updated agent context file
+
+## Key rules
+
+- Use absolute paths for filesystem operations; use project-relative paths for references in documentation and agent context files
+- ERROR on gate failures or unresolved clarifications

.claude/skills/speckit-specify/SKILL.md

@@ -0,0 +1,329 @@
+---
+name: speckit-specify
+description: Create or update the feature specification from a natural language feature description.
+argument-hint: "Describe the feature you want to specify"
+user-invocable: true
+disable-model-invocation: false
+compatibility: "Requires spec-kit project structure with .specify/ directory"
+metadata:
+  author: github-spec-kit
+  source: claude:templates/commands/specify.md
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before specification)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_specify` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` -> `/speckit-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    Wait for the result of the hook command before proceeding to the Outline.
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Outline
+
+The text the user typed after `/speckit.specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `{ARGS}` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
+
+Given that feature description, do this:
+
+1. **Generate a concise short name** (2-4 words) for the feature:
+   - Analyze the feature description and extract the most meaningful keywords
+   - Create a 2-4 word short name that captures the essence of the feature
+   - Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
+   - Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
+   - Keep it concise but descriptive enough to understand the feature at a glance
+   - Examples:
+     - "I want to add user authentication" → "user-auth"
+     - "Implement OAuth2 integration for the API" → "oauth2-api-integration"
+     - "Create a dashboard for analytics" → "analytics-dashboard"
+     - "Fix payment processing timeout bug" → "fix-payment-timeout"
+
+2. **Branch creation** (optional, via hook):
+
+   If a `before_specify` hook ran successfully in the Pre-Execution Checks above, it will have created/switched to a git branch and output JSON containing `BRANCH_NAME` and `FEATURE_NUM`. Note these values for reference, but the branch name does **not** dictate the spec directory name.
+
+   If the user explicitly provided `GIT_BRANCH_NAME`, pass it through to the hook so the branch script uses the exact value as the branch name (bypassing all prefix/suffix generation).
+
+3. **Create the spec feature directory**:
+
+   Specs live under the default `specs/` directory unless the user explicitly provides `SPECIFY_FEATURE_DIRECTORY`.
+
+   **Resolution order for `SPECIFY_FEATURE_DIRECTORY`**:
+   1. If the user explicitly provided `SPECIFY_FEATURE_DIRECTORY` (e.g., via environment variable, argument, or configuration), use it as-is
+   2. Otherwise, auto-generate it under `specs/`:
+      - Check `.specify/init-options.json` for `branch_numbering`
+      - If `"timestamp"`: prefix is `YYYYMMDD-HHMMSS` (current timestamp)
+      - If `"sequential"` or absent: prefix is `NNN` (next available 3-digit number after scanning existing directories in `specs/`)
+      - Construct the directory name: `<prefix>-<short-name>` (e.g., `003-user-auth` or `20260319-143022-user-auth`)
+      - Set `SPECIFY_FEATURE_DIRECTORY` to `specs/<directory-name>`
+
+   **Create the directory and spec file**:
+   - `mkdir -p SPECIFY_FEATURE_DIRECTORY`
+   - Copy `templates/spec-template.md` to `SPECIFY_FEATURE_DIRECTORY/spec.md` as the starting point
+   - Set `SPEC_FILE` to `SPECIFY_FEATURE_DIRECTORY/spec.md`
+   - Persist the resolved path to `.specify/feature.json`:
+     ```json
+     {
+       "feature_directory": "<resolved feature dir>"
+     }
+     ```
+     Write the actual resolved directory path value (for example, `specs/003-user-auth`), not the literal string `SPECIFY_FEATURE_DIRECTORY`.
+     This allows downstream commands (`/speckit.plan`, `/speckit.tasks`, etc.) to locate the feature directory without relying on git branch name conventions.
+
+   **IMPORTANT**:
+   - You must only create one feature per `/speckit.specify` invocation
+   - The spec directory name and the git branch name are independent — they may be the same but that is the user's choice
+   - The spec directory and file are always created by this command, never by the hook
+
+4. Load `templates/spec-template.md` to understand required sections.
+
+5. Follow this execution flow:
+    1. Parse user description from arguments
+       If empty: ERROR "No feature description provided"
+    2. Extract key concepts from description
+       Identify: actors, actions, data, constraints
+    3. For unclear aspects:
+       - Make informed guesses based on context and industry standards
+       - Only mark with [NEEDS CLARIFICATION: specific question] if:
+         - The choice significantly impacts feature scope or user experience
+         - Multiple reasonable interpretations exist with different implications
+         - No reasonable default exists
+       - **LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total**
+       - Prioritize clarifications by impact: scope > security/privacy > user experience > technical details
+    4. Fill User Scenarios & Testing section
+       If no clear user flow: ERROR "Cannot determine user scenarios"
+    5. Generate Functional Requirements
+       Each requirement must be testable
+       Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
+    6. Define Success Criteria
+       Create measurable, technology-agnostic outcomes
+       Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion)
+       Each criterion must be verifiable without implementation details
+    7. Identify Key Entities (if data involved)
+    8. Return: SUCCESS (spec ready for planning)
+
+6. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+
+7. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
+
+   a. **Create Spec Quality Checklist**: Generate a checklist file at `SPECIFY_FEATURE_DIRECTORY/checklists/requirements.md` using the checklist template structure with these validation items:
+
+      ```markdown
+      # Specification Quality Checklist: [FEATURE NAME]
+      
+      **Purpose**: Validate specification completeness and quality before proceeding to planning
+      **Created**: [DATE]
+      **Feature**: [Link to spec.md]
+      
+      ## Content Quality
+      
+      - [ ] No implementation details (languages, frameworks, APIs)
+      - [ ] Focused on user value and business needs
+      - [ ] Written for non-technical stakeholders
+      - [ ] All mandatory sections completed
+      
+      ## Requirement Completeness
+      
+      - [ ] No [NEEDS CLARIFICATION] markers remain
+      - [ ] Requirements are testable and unambiguous
+      - [ ] Success criteria are measurable
+      - [ ] Success criteria are technology-agnostic (no implementation details)
+      - [ ] All acceptance scenarios are defined
+      - [ ] Edge cases are identified
+      - [ ] Scope is clearly bounded
+      - [ ] Dependencies and assumptions identified
+      
+      ## Feature Readiness
+      
+      - [ ] All functional requirements have clear acceptance criteria
+      - [ ] User scenarios cover primary flows
+      - [ ] Feature meets measurable outcomes defined in Success Criteria
+      - [ ] No implementation details leak into specification
+      
+      ## Notes
+      
+      - Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`
+      ```
+
+   b. **Run Validation Check**: Review the spec against each checklist item:
+      - For each item, determine if it passes or fails
+      - Document specific issues found (quote relevant spec sections)
+
+   c. **Handle Validation Results**:
+
+      - **If all items pass**: Mark checklist complete and proceed to step 7
+
+      - **If items fail (excluding [NEEDS CLARIFICATION])**:
+        1. List the failing items and specific issues
+        2. Update the spec to address each issue
+        3. Re-run validation until all items pass (max 3 iterations)
+        4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user
+
+      - **If [NEEDS CLARIFICATION] markers remain**:
+        1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec
+        2. **LIMIT CHECK**: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest
+        3. For each clarification needed (max 3), present options to user in this format:
+
+           ```markdown
+           ## Question [N]: [Topic]
+           
+           **Context**: [Quote relevant spec section]
+           
+           **What we need to know**: [Specific question from NEEDS CLARIFICATION marker]
+           
+           **Suggested Answers**:
+           
+           | Option | Answer | Implications |
+           |--------|--------|--------------|
+           | A      | [First suggested answer] | [What this means for the feature] |
+           | B      | [Second suggested answer] | [What this means for the feature] |
+           | C      | [Third suggested answer] | [What this means for the feature] |
+           | Custom | Provide your own answer | [Explain how to provide custom input] |
+           
+           **Your choice**: _[Wait for user response]_
+           ```
+
+        4. **CRITICAL - Table Formatting**: Ensure markdown tables are properly formatted:
+           - Use consistent spacing with pipes aligned
+           - Each cell should have spaces around content: `| Content |` not `|Content|`
+           - Header separator must have at least 3 dashes: `|--------|`
+           - Test that the table renders correctly in markdown preview
+        5. Number questions sequentially (Q1, Q2, Q3 - max 3 total)
+        6. Present all questions together before waiting for responses
+        7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
+        8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
+        9. Re-run validation after all clarifications are resolved
+
+   d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status
+
+8. **Report completion** to the user with:
+   - `SPECIFY_FEATURE_DIRECTORY` — the feature directory path
+   - `SPEC_FILE` — the spec file path
+   - Checklist results summary
+   - Readiness for the next phase (`/speckit.clarify` or `/speckit.plan`)
+
+9. **Check for extension hooks**: After reporting completion, check if `.specify/extensions.yml` exists in the project root.
+   - If it exists, read it and look for entries under the `hooks.after_specify` key
+   - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+   - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+   - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+     - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+     - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+   - When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` -> `/speckit-git-commit`.
+   - For each executable hook, output the following based on its `optional` flag:
+     - **Optional hook** (`optional: true`):
+       ```
+       ## Extension Hooks
+
+       **Optional Hook**: {extension}
+       Command: `/{command}`
+       Description: {description}
+
+       Prompt: {prompt}
+       To execute: `/{command}`
+       ```
+     - **Mandatory hook** (`optional: false`):
+       ```
+       ## Extension Hooks
+
+       **Automatic Hook**: {extension}
+       Executing: `/{command}`
+       EXECUTE_COMMAND: {command}
+       ```
+   - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+**NOTE:** Branch creation is handled by the `before_specify` hook (git extension). Spec directory and file creation are always handled by this core command.
+
+## Quick Guidelines
+
+- Focus on **WHAT** users need and **WHY**.
+- Avoid HOW to implement (no tech stack, APIs, code structure).
+- Written for business stakeholders, not developers.
+- DO NOT create any checklists that are embedded in the spec. That will be a separate command.
+
+### Section Requirements
+
+- **Mandatory sections**: Must be completed for every feature
+- **Optional sections**: Include only when relevant to the feature
+- When a section doesn't apply, remove it entirely (don't leave as "N/A")
+
+### For AI Generation
+
+When creating this spec from a user prompt:
+
+1. **Make informed guesses**: Use context, industry standards, and common patterns to fill gaps
+2. **Document assumptions**: Record reasonable defaults in the Assumptions section
+3. **Limit clarifications**: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
+   - Significantly impact feature scope or user experience
+   - Have multiple reasonable interpretations with different implications
+   - Lack any reasonable default
+4. **Prioritize clarifications**: scope > security/privacy > user experience > technical details
+5. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
+6. **Common areas needing clarification** (only if no reasonable default exists):
+   - Feature scope and boundaries (include/exclude specific use cases)
+   - User types and permissions (if multiple conflicting interpretations possible)
+   - Security/compliance requirements (when legally/financially significant)
+
+**Examples of reasonable defaults** (don't ask about these):
+
+- Data retention: Industry-standard practices for the domain
+- Performance targets: Standard web/mobile app expectations unless specified
+- Error handling: User-friendly messages with appropriate fallbacks
+- Authentication method: Standard session-based or OAuth2 for web apps
+- Integration patterns: Use project-appropriate patterns (REST/GraphQL for web services, function calls for libraries, CLI args for tools, etc.)
+
+### Success Criteria Guidelines
+
+Success criteria must be:
+
+1. **Measurable**: Include specific metrics (time, percentage, count, rate)
+2. **Technology-agnostic**: No mention of frameworks, languages, databases, or tools
+3. **User-focused**: Describe outcomes from user/business perspective, not system internals
+4. **Verifiable**: Can be tested/validated without knowing implementation details
+
+**Good examples**:
+
+- "Users can complete checkout in under 3 minutes"
+- "System supports 10,000 concurrent users"
+- "95% of searches return results in under 1 second"
+- "Task completion rate improves by 40%"
+
+**Bad examples** (implementation-focused):
+
+- "API response time is under 200ms" (too technical, use "Users see results instantly")
+- "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
+- "React components render efficiently" (framework-specific)
+- "Redis cache hit rate above 80%" (technology-specific)

.claude/skills/speckit-tasks/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: speckit-tasks
+description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
+argument-hint: "Optional task generation constraints"
+user-invocable: true
+disable-model-invocation: false
+compatibility: "Requires spec-kit project structure with .specify/ directory"
+metadata:
+  author: github-spec-kit
+  source: claude:templates/commands/tasks.md
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before tasks generation)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_tasks` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` -> `/speckit-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+    
+    Wait for the result of the hook command before proceeding to the Outline.
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Outline
+
+1. **Setup**: Run `{SCRIPT}` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load design documents**: Read from FEATURE_DIR:
+   - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
+   - **Optional**: data-model.md (entities), contracts/ (interface contracts), research.md (decisions), quickstart.md (test scenarios)
+   - Note: Not all projects have all documents. Generate tasks based on what's available.
+
+3. **Execute task generation workflow**:
+   - Load plan.md and extract tech stack, libraries, project structure
+   - Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)
+   - If data-model.md exists: Extract entities and map to user stories
+   - If contracts/ exists: Map interface contracts to user stories
+   - If research.md exists: Extract decisions for setup tasks
+   - Generate tasks organized by user story (see Task Generation Rules below)
+   - Generate dependency graph showing user story completion order
+   - Create parallel execution examples per user story
+   - Validate task completeness (each user story has all needed tasks, independently testable)
+
+4. **Generate tasks.md**: Use `templates/tasks-template.md` as structure, fill with:
+   - Correct feature name from plan.md
+   - Phase 1: Setup tasks (project initialization)
+   - Phase 2: Foundational tasks (blocking prerequisites for all user stories)
+   - Phase 3+: One phase per user story (in priority order from spec.md)
+   - Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
+   - Final Phase: Polish & cross-cutting concerns
+   - All tasks must follow the strict checklist format (see Task Generation Rules below)
+   - Clear file paths for each task
+   - Dependencies section showing story completion order
+   - Parallel execution examples per story
+   - Implementation strategy section (MVP first, incremental delivery)
+
+5. **Report**: Output path to generated tasks.md and summary:
+   - Total task count
+   - Task count per user story
+   - Parallel opportunities identified
+   - Independent test criteria for each story
+   - Suggested MVP scope (typically just User Story 1)
+   - Format validation: Confirm ALL tasks follow the checklist format (checkbox, ID, labels, file paths)
+
+6. **Check for extension hooks**: After tasks.md is generated, check if `.specify/extensions.yml` exists in the project root.
+   - If it exists, read it and look for entries under the `hooks.after_tasks` key
+   - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+   - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+   - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+     - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+     - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+   - When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` -> `/speckit-git-commit`.
+   - For each executable hook, output the following based on its `optional` flag:
+     - **Optional hook** (`optional: true`):
+       ```
+       ## Extension Hooks
+
+       **Optional Hook**: {extension}
+       Command: `/{command}`
+       Description: {description}
+
+       Prompt: {prompt}
+       To execute: `/{command}`
+       ```
+     - **Mandatory hook** (`optional: false`):
+       ```
+       ## Extension Hooks
+
+       **Automatic Hook**: {extension}
+       Executing: `/{command}`
+       EXECUTE_COMMAND: {command}
+       ```
+   - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+Context for task generation: {ARGS}
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
+
+## Task Generation Rules
+
+**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.
+
+**Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.
+
+### Checklist Format (REQUIRED)
+
+Every task MUST strictly follow this format:
+
+```text
+- [ ] [TaskID] [P?] [Story?] Description with file path
+```
+
+**Format Components**:
+
+1. **Checkbox**: ALWAYS start with `- [ ]` (markdown checkbox)
+2. **Task ID**: Sequential number (T001, T002, T003...) in execution order
+3. **[P] marker**: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks)
+4. **[Story] label**: REQUIRED for user story phase tasks only
+   - Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
+   - Setup phase: NO story label
+   - Foundational phase: NO story label  
+   - User Story phases: MUST have story label
+   - Polish phase: NO story label
+5. **Description**: Clear action with exact file path
+
+**Examples**:
+
+- ✅ CORRECT: `- [ ] T001 Create project structure per implementation plan`
+- ✅ CORRECT: `- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py`
+- ✅ CORRECT: `- [ ] T012 [P] [US1] Create User model in src/models/user.py`
+- ✅ CORRECT: `- [ ] T014 [US1] Implement UserService in src/services/user_service.py`
+- ❌ WRONG: `- [ ] Create User model` (missing ID and Story label)
+- ❌ WRONG: `T001 [US1] Create model` (missing checkbox)
+- ❌ WRONG: `- [ ] [US1] Create User model` (missing Task ID)
+- ❌ WRONG: `- [ ] T001 [US1] Create model` (missing file path)
+
+### Task Organization
+
+1. **From User Stories (spec.md)** - PRIMARY ORGANIZATION:
+   - Each user story (P1, P2, P3...) gets its own phase
+   - Map all related components to their story:
+     - Models needed for that story
+     - Services needed for that story
+     - Interfaces/UI needed for that story
+     - If tests requested: Tests specific to that story
+   - Mark story dependencies (most stories should be independent)
+
+2. **From Contracts**:
+   - Map each interface contract → to the user story it serves
+   - If tests requested: Each interface contract → contract test task [P] before implementation in that story's phase
+
+3. **From Data Model**:
+   - Map each entity to the user story(ies) that need it
+   - If entity serves multiple stories: Put in earliest story or Setup phase
+   - Relationships → service layer tasks in appropriate story phase
+
+4. **From Setup/Infrastructure**:
+   - Shared infrastructure → Setup phase (Phase 1)
+   - Foundational/blocking tasks → Foundational phase (Phase 2)
+   - Story-specific setup → within that story's phase
+
+### Phase Structure
+
+- **Phase 1**: Setup (project initialization)
+- **Phase 2**: Foundational (blocking prerequisites - MUST complete before user stories)
+- **Phase 3+**: User Stories in priority order (P1, P2, P3...)
+  - Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
+  - Each phase should be a complete, independently testable increment
+- **Final Phase**: Polish & Cross-Cutting Concerns

.claude/skills/speckit-taskstoissues/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: speckit-taskstoissues
+description: Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts.
+argument-hint: "Optional filter or label for GitHub issues"
+user-invocable: true
+disable-model-invocation: false
+compatibility: "Requires spec-kit project structure with .specify/ directory"
+metadata:
+  author: github-spec-kit
+  source: claude:templates/commands/taskstoissues.md
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before tasks-to-issues conversion)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_taskstoissues` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` -> `/speckit-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    Wait for the result of the hook command before proceeding to the Outline.
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Outline
+
+1. Run `{SCRIPT}` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+1. From the executed script, extract the path to **tasks**.
+1. Get the Git remote by running:
+
+```bash
+git config --get remote.origin.url
+```
+
+> [!CAUTION]
+> ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL
+
+1. For each task in the list, use the GitHub MCP server to create a new issue in the repository that is representative of the Git remote.
+
+> [!CAUTION]
+> UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL
+
+## Post-Execution Checks
+
+**Check for extension hooks (after tasks-to-issues conversion)**:
+Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.after_taskstoissues` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` -> `/speckit-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently

.dockerignore

@@ -1,8 +0,0 @@
-.git
-.gitignore
-*.md
-node_modules
-.env
-.env.*
-scripts/
-start.sh

.github/FUNDING.yml

@@ -0,0 +1,9 @@
+# GitHub recognizes this file and shows a "Sponsor" button on the repo page.
+# Add other platforms here as they get set up. Empty / commented-out entries
+# are skipped silently.
+
+buy_me_a_coffee: dtzp555
+
+# github: [dtzp555-max]   # uncomment after GitHub Sponsors enrollment is approved
+# ko_fi: dtzp555
+# custom: ["https://example.com/donate"]

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,56 @@
+# Pull Request
+
+## Summary
+
+<!-- One or two sentences describing the change and why it is in scope for OCP. -->
+
+## Claude Code Alignment Evidence (REQUIRED)
+
+Per `ALIGNMENT.md`, every PR that touches `server.mjs` or any network-facing surface must fill out this section. PRs with this section blank or unchecked will receive a `request changes` review and cannot be merged.
+
+- [ ] **Corresponding `cli.js` reference.** I have identified the `cli.js` function and line range that performs the operation this PR forwards. Citation (format `cli.js:NNNN` or `cli.js vE4 <functionName>`):
+  <!-- e.g. cli.js:18423-18467 (function: sendUserMessage)  -->
+
+- [ ] **If `cli.js` does not perform this operation**, I have stated this explicitly below and justified the scope under `ALIGNMENT.md` Rule 2. (Note: in almost all cases this means the PR should be closed, not merged. Proxy layers do not invent endpoints.)
+  <!-- Justification, if applicable. Empty is fine when cli.js does perform the operation. -->
+
+- [ ] **Commit message citations.** Every "Claude Code uses X" or "cli.js uses X" assertion in every commit of this PR is immediately followed by a `cli.js:NNNN` or `cli.js vE4 <functionName>` citation. I have verified this by rereading each commit message.
+
+## Type of change
+
+- [ ] Bug fix (alignment with existing `cli.js` behavior)
+- [ ] Feature (new `cli.js` behavior now surfaced through OCP)
+- [ ] Refactor (no wire-level behavior change)
+- [ ] Deletion (unalignable feature removal per `ALIGNMENT.md` Unalignable Policy)
+- [ ] Documentation / governance
+
+## Reviewer checklist
+
+Reviewers: this section is for you, not the author. Do not approve until every box is checked.
+
+- [ ] I opened `cli.js` at the cited line range and confirmed the operation matches.
+- [ ] I ran (or confirmed CI ran) `.github/workflows/alignment.yml` and it passed.
+- [ ] I am not the commit author of any commit in this PR (Iron Rule 10).
+- [ ] If the PR asserts scope without a `cli.js` citation, I confirmed the justification is sound per `ALIGNMENT.md` Rule 2.
+
+## Related
+
+- `ALIGNMENT.md` Rule(s) invoked: <!-- e.g. Rule 3 -->
+- Related issue / prior PR: <!-- #NNN -->
+- Historical lesson reference (if relevant): <!-- e.g. 2026-04-11 drift, b87992f -->
+
+### User-visible change self-check (铁律第五律 5.3)
+
+- [ ] This PR has user-visible changes → README has corresponding documentation (paste diff link or line range)
+- [ ] This PR has no user-visible changes → stated "no user-visible change" in summary above
+
+Reviewers: if "user-visible" is checked but README diff is empty, block merge (per 5.3 reviewer gate).
+
+### Privacy self-check (for PUBLIC repos) — Iron Rule adjacent
+
+- [ ] This PR does not introduce real names, nicknames, or handles that identify specific individuals. All references use role-based terms (`project maintainer`, `contributor`, `user`, `reviewer`).
+- [ ] This PR does not introduce literal personal paths (`/Users/<username>/`, `/home/<username>/`). Uses `$HOME/` or `~/` instead.
+- [ ] This PR does not introduce personal machine hostnames. Uses role-based names or generic descriptors.
+- [ ] This PR does not introduce personal email addresses beyond automated placeholders like `noreply@<vendor>.com`.
+
+Reviewers: if any of the above is violated and the repo is PUBLIC, block merge and request scrub.

.github/workflows/alignment.yml

@@ -0,0 +1,123 @@
+name: Alignment Guardrail
+
+on:
+  pull_request:
+    paths:
+      - 'server.mjs'
+      - '.github/workflows/alignment.yml'
+
+jobs:
+  blacklist:
+    name: server.mjs blacklist (hard fail)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Scan server.mjs for hallucinated tokens
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if [ ! -f server.mjs ]; then
+            echo "server.mjs not found; nothing to scan."
+            exit 0
+          fi
+
+          # Known-hallucinated tokens. Extend only via an ALIGNMENT.md amendment PR.
+          # Each token is matched as a fixed string against server.mjs only.
+          BLACKLIST=(
+            "api.anthropic.com/api/oauth/usage"
+          )
+
+          FAIL=0
+          for token in "${BLACKLIST[@]}"; do
+            if sed "s|//.*\$||" server.mjs | grep -n -F "$token"; then
+              echo "::error file=server.mjs::Blacklisted token '$token' detected in server.mjs."
+              FAIL=1
+            fi
+          done
+
+          if [ "$FAIL" -ne 0 ]; then
+            cat <<'EOF'
+
+          ============================================================
+          ALIGNMENT GUARDRAIL FAILURE
+          ============================================================
+          server.mjs contains a token on the OCP alignment blacklist.
+
+          These tokens were introduced by LLM hallucinations and do
+          not appear in cli.js at any shipped Claude Code version.
+          See ALIGNMENT.md -> "Historical Lesson: The 2026-04-11 Drift"
+          (commit b87992f) for the full incident record.
+
+          Required action:
+            1. Remove the token from server.mjs.
+            2. grep the reference cli.js for the operation you
+               intended and cite the real line numbers.
+            3. See ALIGNMENT.md Rules 1, 2, and 5.
+
+          Do not add allowlist entries to this workflow without an
+          amendment PR to ALIGNMENT.md (see Amendment Procedure).
+          ============================================================
+          EOF
+            exit 1
+          fi
+
+          echo "Blacklist scan clean."
+
+  commit-citation:
+    name: commit message citation (soft check)
+    runs-on: ubuntu-latest
+    # Soft check: reports a warning but does not block merge. Reviewers
+    # are expected to enforce per CLAUDE.md. Escalate to hard-fail via
+    # an ALIGNMENT.md amendment if drift recurs.
+    continue-on-error: true
+    steps:
+      - name: Checkout full history
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Scan PR commits for uncited assertions
+        shell: bash
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          set -euo pipefail
+
+          if [ -z "${BASE_SHA:-}" ] || [ -z "${HEAD_SHA:-}" ]; then
+            echo "No PR context; skipping."
+            exit 0
+          fi
+
+          # Collect commit messages in range.
+          MSGS="$(git log --format=%B "${BASE_SHA}..${HEAD_SHA}")"
+
+          # Look for assertions of the form "Claude Code uses ..." or
+          # "cli.js uses ..." (case-insensitive). For each hit, require
+          # a citation in the same commit message in one of the forms:
+          #   cli.js:NNNN         (line-number citation)
+          #   cli.js vE4 <name>   (version + function-name citation)
+          # Absence of a citation is a soft finding.
+
+          WARN=0
+          # Split log into per-commit blocks for precise matching.
+          git log --format="%H" "${BASE_SHA}..${HEAD_SHA}" | while read -r sha; do
+            BODY="$(git log -1 --format=%B "$sha")"
+            if echo "$BODY" | grep -E -i -q '(claude[[:space:]]+code|cli\.js)[[:space:]]+uses'; then
+              if echo "$BODY" | grep -E -q '(cli\.js:[0-9]+|cli\.js[[:space:]]+v[A-Za-z0-9]+[[:space:]]+[A-Za-z_][A-Za-z0-9_]*)'; then
+                echo "OK  $sha: assertion cited."
+              else
+                echo "::warning::Commit $sha asserts 'Claude Code uses ...' or 'cli.js uses ...' but does not cite a cli.js line number or versioned function name. See CLAUDE.md -> Commit message conventions."
+                WARN=1
+              fi
+            fi
+          done
+
+          if [ "$WARN" -ne 0 ]; then
+            echo "Soft check raised warnings. Reviewer: please enforce per CLAUDE.md."
+          else
+            echo "Commit citation soft check clean."
+          fi

.github/workflows/gitleaks.yml

@@ -0,0 +1,32 @@
+name: gitleaks
+
+# Secret scanning gate. Runs on every PR (any branch) and every push to main.
+# Configuration is read from the repo-root `.gitleaks.toml` automatically.
+# Hard-fails the build on any detected leak — public repo, no tolerance.
+#
+# To extend the allowlist (e.g. a new known-safe placeholder), edit
+# `.gitleaks.toml`. Do not add `continue-on-error` here without an explicit
+# governance decision.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  scan:
+    name: gitleaks scan (hard fail)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout (full history)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run gitleaks
+        uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: Auto Release on Tag
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Extract version from tag
+        id: ver
+        run: echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+      - name: Extract CHANGELOG section
+        id: notes
+        run: |
+          VERSION="${{ steps.ver.outputs.version }}"
+          # Extract section for this version from CHANGELOG.md
+          # Pattern: "## v${VERSION}" through the next "## " or EOF
+          if [ ! -f CHANGELOG.md ]; then
+            echo "No CHANGELOG.md found; using minimal release notes"
+            echo "notes=Release v${VERSION}" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+          awk -v ver="v${VERSION}" '
+            $0 ~ "^## " ver { found=1; print; next }
+            found && /^## v/ { exit }
+            found { print }
+          ' CHANGELOG.md > /tmp/release-notes.md
+          if [ ! -s /tmp/release-notes.md ]; then
+            echo "No matching section in CHANGELOG for v${VERSION}; using minimal notes"
+            echo "Release v${VERSION}" > /tmp/release-notes.md
+          fi
+          echo "notes_file=/tmp/release-notes.md" >> $GITHUB_OUTPUT
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          if gh release view "v${{ steps.ver.outputs.version }}" >/dev/null 2>&1; then
+            echo "Release v${{ steps.ver.outputs.version }} already exists — skipping"
+            exit 0
+          fi
+          gh release create "v${{ steps.ver.outputs.version }}" \
+            --title "v${{ steps.ver.outputs.version }}" \
+            --notes-file /tmp/release-notes.md \
+            --latest

.github/workflows/test.yml

@@ -0,0 +1,41 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test-features:
+    name: test-features.mjs (smoke)
+    runs-on: ubuntu-latest
+
+    # `test-features.mjs` is self-contained — it runs assertions against the
+    # `keys.mjs` DB layer using a throwaway test database. It does NOT need a
+    # live claude CLI or a running OCP server. So this job runs as a hard
+    # check on every push / PR.
+    #
+    # If a future expansion of the suite adds tests that DO require a live
+    # claude CLI or a running OCP server, mark those steps `continue-on-error:
+    # true` (or split them into a separate job) — CI must not be flaky on
+    # things outside the contributor's machine.
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          # Node 24 ships `node:sqlite` as stable. The test imports keys.mjs,
+          # which uses `import { DatabaseSync } from "node:sqlite"`.
+          # Node 22 also works with `--experimental-sqlite`, but we run on 24
+          # to keep the CI step simple and to match what released OCP runs on.
+          node-version: '24'
+
+      # OCP has zero runtime npm dependencies (package-lock.json shows only
+      # the project's own package and zero external entries). No install
+      # step needed — `node:*` modules are built into Node 24.
+
+      - name: Run test-features.mjs
+        run: npm test

.gitignore

@@ -0,0 +1,15 @@
+# Runtime artifacts
+logs/
+*.log
+
+# Dependencies
+node_modules/
+
+# Environment files
+.env
+.env.*
+
+# Editor / OS scratch
+.DS_Store
+*.swp
+*~

.gitleaks.toml

@@ -0,0 +1,14 @@
+title = "OCP gitleaks configuration"
+
+[allowlist]
+description = "OCP known-safe allowlist"
+regexes = [
+  # Public OAuth client ID for Claude Code PKCE flow (constant, not a secret)
+  '''9d1c250a-e61b-44d9-88ed-5944d1962f5e''',
+  # OCP README API key placeholder example
+  '''ocp_(example|XXX+|xxxx+)''',
+]
+paths = [
+  # Old plan doc with test-admin-123 placeholders
+  '''docs/superpowers/plans/2026-04-10-lan-mode\.md''',
+]

.specify/templates/checklist-template.md

@@ -0,0 +1,40 @@
+# [CHECKLIST TYPE] Checklist: [FEATURE NAME]
+
+**Purpose**: [Brief description of what this checklist covers]
+**Created**: [DATE]
+**Feature**: [Link to spec.md or relevant documentation]
+
+**Note**: This checklist is generated by the `/speckit.checklist` command based on feature context and requirements.
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The checklist items below are SAMPLE ITEMS for illustration only.
+  
+  The /speckit.checklist command MUST replace these with actual items based on:
+  - User's specific checklist request
+  - Feature requirements from spec.md
+  - Technical context from plan.md
+  - Implementation details from tasks.md
+  
+  DO NOT keep these sample items in the generated checklist file.
+  ============================================================================
+-->
+
+## [Category 1]
+
+- [ ] CHK001 First checklist item with clear action
+- [ ] CHK002 Second checklist item
+- [ ] CHK003 Third checklist item
+
+## [Category 2]
+
+- [ ] CHK004 Another category item
+- [ ] CHK005 Item with specific criteria
+- [ ] CHK006 Final item in this category
+
+## Notes
+
+- Check items off as completed: `[x]`
+- Add comments or findings inline
+- Link to relevant resources or documentation
+- Items are numbered sequentially for easy reference

.specify/templates/constitution-template.md

@@ -0,0 +1,50 @@
+# [PROJECT_NAME] Constitution
+<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
+
+## Core Principles
+
+### [PRINCIPLE_1_NAME]
+<!-- Example: I. Library-First -->
+[PRINCIPLE_1_DESCRIPTION]
+<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
+
+### [PRINCIPLE_2_NAME]
+<!-- Example: II. CLI Interface -->
+[PRINCIPLE_2_DESCRIPTION]
+<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
+
+### [PRINCIPLE_3_NAME]
+<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
+[PRINCIPLE_3_DESCRIPTION]
+<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
+
+### [PRINCIPLE_4_NAME]
+<!-- Example: IV. Integration Testing -->
+[PRINCIPLE_4_DESCRIPTION]
+<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
+
+### [PRINCIPLE_5_NAME]
+<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
+[PRINCIPLE_5_DESCRIPTION]
+<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
+
+## [SECTION_2_NAME]
+<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
+
+[SECTION_2_CONTENT]
+<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
+
+## [SECTION_3_NAME]
+<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
+
+[SECTION_3_CONTENT]
+<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
+
+## Governance
+<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
+
+[GOVERNANCE_RULES]
+<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
+
+**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
+<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->

.specify/templates/plan-template.md

@@ -0,0 +1,104 @@
+# Implementation Plan: [FEATURE]
+
+**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
+**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
+
+**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/plan-template.md` for the execution workflow.
+
+## Summary
+
+[Extract from feature spec: primary requirement + technical approach from research]
+
+## Technical Context
+
+<!--
+  ACTION REQUIRED: Replace the content in this section with the technical details
+  for the project. The structure here is presented in advisory capacity to guide
+  the iteration process.
+-->
+
+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
+**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]  
+**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
+**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
+**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
+**Project Type**: [e.g., library/cli/web-service/mobile-app/compiler/desktop-app or NEEDS CLARIFICATION]  
+**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]  
+**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]  
+**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+[Gates determined based on constitution file]
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/[###-feature]/
+├── plan.md              # This file (/speckit.plan command output)
+├── research.md          # Phase 0 output (/speckit.plan command)
+├── data-model.md        # Phase 1 output (/speckit.plan command)
+├── quickstart.md        # Phase 1 output (/speckit.plan command)
+├── contracts/           # Phase 1 output (/speckit.plan command)
+└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
+```
+
+### Source Code (repository root)
+<!--
+  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
+  for this feature. Delete unused options and expand the chosen structure with
+  real paths (e.g., apps/admin, packages/something). The delivered plan must
+  not include Option labels.
+-->
+
+```text
+# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
+src/
+├── models/
+├── services/
+├── cli/
+└── lib/
+
+tests/
+├── contract/
+├── integration/
+└── unit/
+
+# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
+backend/
+├── src/
+│   ├── models/
+│   ├── services/
+│   └── api/
+└── tests/
+
+frontend/
+├── src/
+│   ├── components/
+│   ├── pages/
+│   └── services/
+└── tests/
+
+# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
+api/
+└── [same as backend above]
+
+ios/ or android/
+└── [platform-specific structure: feature modules, UI flows, platform tests]
+```
+
+**Structure Decision**: [Document the selected structure and reference the real
+directories captured above]
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
+| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |

.specify/templates/spec-template.md

@@ -0,0 +1,128 @@
+# Feature Specification: [FEATURE NAME]
+
+**Feature Branch**: `[###-feature-name]`  
+**Created**: [DATE]  
+**Status**: Draft  
+**Input**: User description: "$ARGUMENTS"
+
+## User Scenarios & Testing *(mandatory)*
+
+<!--
+  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
+  you should still have a viable MVP (Minimum Viable Product) that delivers value.
+  
+  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+  Think of each story as a standalone slice of functionality that can be:
+  - Developed independently
+  - Tested independently
+  - Deployed independently
+  - Demonstrated to users independently
+-->
+
+### User Story 1 - [Brief Title] (Priority: P1)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 2 - [Brief Title] (Priority: P2)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 3 - [Brief Title] (Priority: P3)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+[Add more user stories as needed, each with an assigned priority]
+
+### Edge Cases
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right edge cases.
+-->
+
+- What happens when [boundary condition]?
+- How does system handle [error scenario]?
+
+## Requirements *(mandatory)*
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right functional requirements.
+-->
+
+### Functional Requirements
+
+- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
+- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]  
+- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
+- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
+- **FR-005**: System MUST [behavior, e.g., "log all security events"]
+
+*Example of marking unclear requirements:*
+
+- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
+- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
+
+### Key Entities *(include if feature involves data)*
+
+- **[Entity 1]**: [What it represents, key attributes without implementation]
+- **[Entity 2]**: [What it represents, relationships to other entities]
+
+## Success Criteria *(mandatory)*
+
+<!--
+  ACTION REQUIRED: Define measurable success criteria.
+  These must be technology-agnostic and measurable.
+-->
+
+### Measurable Outcomes
+
+- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
+- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
+- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
+- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]
+
+## Assumptions
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right assumptions based on reasonable defaults
+  chosen when the feature description did not specify certain details.
+-->
+
+- [Assumption about target users, e.g., "Users have stable internet connectivity"]
+- [Assumption about scope boundaries, e.g., "Mobile support is out of scope for v1"]
+- [Assumption about data/environment, e.g., "Existing authentication system will be reused"]
+- [Dependency on existing system/service, e.g., "Requires access to the existing user profile API"]

.specify/templates/tasks-template.md

@@ -0,0 +1,251 @@
+---
+
+description: "Task list template for feature implementation"
+---
+
+# Tasks: [FEATURE NAME]
+
+**Input**: Design documents from `/specs/[###-feature-name]/`
+**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
+
+**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- **Single project**: `src/`, `tests/` at repository root
+- **Web app**: `backend/src/`, `frontend/src/`
+- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
+- Paths shown below assume single project - adjust based on plan.md structure
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
+  
+  The /speckit.tasks command MUST replace these with actual tasks based on:
+  - User stories from spec.md (with their priorities P1, P2, P3...)
+  - Feature requirements from plan.md
+  - Entities from data-model.md
+  - Endpoints from contracts/
+  
+  Tasks MUST be organized by user story so each story can be:
+  - Implemented independently
+  - Tested independently
+  - Delivered as an MVP increment
+  
+  DO NOT keep these sample tasks in the generated tasks.md file.
+  ============================================================================
+-->
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Project initialization and basic structure
+
+- [ ] T001 Create project structure per implementation plan
+- [ ] T002 Initialize [language] project with [framework] dependencies
+- [ ] T003 [P] Configure linting and formatting tools
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+Examples of foundational tasks (adjust based on your project):
+
+- [ ] T004 Setup database schema and migrations framework
+- [ ] T005 [P] Implement authentication/authorization framework
+- [ ] T006 [P] Setup API routing and middleware structure
+- [ ] T007 Create base models/entities that all stories depend on
+- [ ] T008 Configure error handling and logging infrastructure
+- [ ] T009 Setup environment configuration management
+
+**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
+
+---
+
+## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
+
+- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 1
+
+- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
+- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
+- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
+- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T016 [US1] Add validation and error handling
+- [ ] T017 [US1] Add logging for user story 1 operations
+
+**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
+
+---
+
+## Phase 4: User Story 2 - [Title] (Priority: P2)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 2
+
+- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py
+- [ ] T021 [US2] Implement [Service] in src/services/[service].py
+- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T023 [US2] Integrate with User Story 1 components (if needed)
+
+**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently
+
+---
+
+## Phase 5: User Story 3 - [Title] (Priority: P3)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 3
+
+- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py
+- [ ] T027 [US3] Implement [Service] in src/services/[service].py
+- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py
+
+**Checkpoint**: All user stories should now be independently functional
+
+---
+
+[Add more user story phases as needed, following the same pattern]
+
+---
+
+## Phase N: Polish & Cross-Cutting Concerns
+
+**Purpose**: Improvements that affect multiple user stories
+
+- [ ] TXXX [P] Documentation updates in docs/
+- [ ] TXXX Code cleanup and refactoring
+- [ ] TXXX Performance optimization across all stories
+- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/
+- [ ] TXXX Security hardening
+- [ ] TXXX Run quickstart.md validation
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies - can start immediately
+- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
+- **User Stories (Phase 3+)**: All depend on Foundational phase completion
+  - User stories can then proceed in parallel (if staffed)
+  - Or sequentially in priority order (P1 → P2 → P3)
+- **Polish (Final Phase)**: Depends on all desired user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
+- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable
+- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable
+
+### Within Each User Story
+
+- Tests (if included) MUST be written and FAIL before implementation
+- Models before services
+- Services before endpoints
+- Core implementation before integration
+- Story complete before moving to next priority
+
+### Parallel Opportunities
+
+- All Setup tasks marked [P] can run in parallel
+- All Foundational tasks marked [P] can run in parallel (within Phase 2)
+- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
+- All tests for a user story marked [P] can run in parallel
+- Models within a story marked [P] can run in parallel
+- Different user stories can be worked on in parallel by different team members
+
+---
+
+## Parallel Example: User Story 1
+
+```bash
+# Launch all tests for User Story 1 together (if tests requested):
+Task: "Contract test for [endpoint] in tests/contract/test_[name].py"
+Task: "Integration test for [user journey] in tests/integration/test_[name].py"
+
+# Launch all models for User Story 1 together:
+Task: "Create [Entity1] model in src/models/[entity1].py"
+Task: "Create [Entity2] model in src/models/[entity2].py"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup
+2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
+3. Complete Phase 3: User Story 1
+4. **STOP and VALIDATE**: Test User Story 1 independently
+5. Deploy/demo if ready
+
+### Incremental Delivery
+
+1. Complete Setup + Foundational → Foundation ready
+2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
+3. Add User Story 2 → Test independently → Deploy/Demo
+4. Add User Story 3 → Test independently → Deploy/Demo
+5. Each story adds value without breaking previous stories
+
+### Parallel Team Strategy
+
+With multiple developers:
+
+1. Team completes Setup + Foundational together
+2. Once Foundational is done:
+   - Developer A: User Story 1
+   - Developer B: User Story 2
+   - Developer C: User Story 3
+3. Stories complete and integrate independently
+
+---
+
+## Notes
+
+- [P] tasks = different files, no dependencies
+- [Story] label maps task to specific user story for traceability
+- Each user story should be independently completable and testable
+- Verify tests fail before implementing
+- Commit after each task or logical group
+- Stop at any checkpoint to validate story independently
+- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence

AGENTS.md

@@ -0,0 +1,74 @@
+Inherits: @~/.cc-rules/AGENTS.md
+
+# OCP — Open Claude Proxy — Agent Guidelines
+
+**Scope**: the `dtzp555-max/ocp` repository.
+**Audience**: any AI coding agent (Claude Code / Cursor / OpenCode / Copilot / Codex / Gemini) touching OCP source.
+
+---
+
+## What this project is
+
+OCP (Open Claude Proxy) is an open-source HTTP gateway that sits between the Claude Code CLI (`cli.js`) and Anthropic's public API. It forwards, observes, and multiplexes traffic that `cli.js` already emits — it is explicitly **not** an extension layer. A secondary role: registering OCP as a local provider inside OpenClaw (a sibling IDE-agnostic tool), so that users running OpenClaw against OCP see the same model list as native Claude Code.
+
+Runtime: Node.js (ESM, `.mjs` throughout). No build step. No bundler. `server.mjs` is the single executable entrypoint; `ocp` and `ocp-connect` are CLI wrappers.
+
+---
+
+## Stack
+
+- Node.js >=18, native ESM modules
+- `http`/`https` built-ins for the proxy core (no Express, no Fastify)
+- `models.json` as the single source of truth for model metadata
+- GitHub Actions for CI (`alignment.yml`, `release.yml`)
+- `gh` CLI assumed for PR creation and release automation
+- No TypeScript. No test framework beyond `test-features.mjs` (run via `npm test`; CI workflow `.github/workflows/test.yml`). Keep dependencies minimal.
+
+---
+
+## Key files to know
+
+- `server.mjs` — the proxy itself; every request path lives here. Governed by `ALIGNMENT.md`.
+- `models.json` — single source of truth for model IDs, aliases, and context windows. See ADR 0003.
+- `setup.mjs` — first-time installer; reads `models.json` to derive bootstrap config.
+- `scripts/sync-openclaw.mjs` — idempotent OpenClaw registry sync invoked by `ocp update`. See ADR 0004.
+- `ocp` — user-facing CLI (install, update, start, stop, status, logs, etc.).
+- `ALIGNMENT.md` — the constitution. Binding for any `server.mjs` change. See ADR 0002.
+- `.github/workflows/alignment.yml` — CI blacklist grep; fails the build on known-hallucinated tokens.
+- `CLAUDE.md` — Claude-Code-specific session instructions + release_kit overlay (Iron Rule 5.5).
+- `docs/adr/` — Architecture Decision Records. Read these before proposing governance or SPOT changes. See `docs/adr/README.md` for the index.
+- `docs/superpowers/plans/` — active spec-kit plans. `docs/superpowers/plans/shipped/` archives plans that have been delivered (don't propose changes against shipped plans — they're history). `docs/superpowers/specs/` holds long-lived design documents that other code references (e.g., the SSE heartbeat design referenced from `server.mjs`).
+- `memory/constitution.md` — spec-kit's project constitution (its standard `memory/` location). Distinct from `~/.cc-rules/memory/` (cross-machine personal memory) and from this repo's `ALIGNMENT.md` (the OCP code-level constitution).
+
+---
+
+## Project-specific constraints
+
+- **`ALIGNMENT.md` is binding.** Any PR touching `server.mjs` must cite `cli.js:NNNN` (or `cli.js vE4 <functionName>`) in the commit body and PR description. See `CLAUDE.md` § "Hard requirements for `server.mjs` changes" and ADR 0002.
+- **Alignment CI is not suppressible.** The `alignment.yml` workflow greps `server.mjs` for known-hallucinated tokens (currently blocking `api.anthropic.com/api/oauth/usage`). Adding new tokens is done via PR amendment to `alignment.yml`; removing entries requires an `ALIGNMENT.md` amendment PR.
+- **No self-approval.** Implementation author cannot merge their own PR (Iron Rule 10). A fresh-context reviewer must open `cli.js` at the cited lines and confirm in the review comment.
+- **`models.json` is the only place to add/edit models.** Do not touch `MODEL_MAP` or `MODELS` arrays directly in `server.mjs` or `setup.mjs`. See ADR 0003.
+- **OpenClaw boundary.** `scripts/sync-openclaw.mjs` only writes `models.providers["claude-local"].models` and `agents.defaults.models["claude-local/*"]` in `~/.openclaw/openclaw.json`. Do not expand scope. See ADR 0004.
+
+---
+
+## Release protocol
+
+OCP follows the machine-readable `release_kit:` overlay in `CLAUDE.md` (Iron Rule 5.5). Before any version bump or tag push, re-read that YAML block and walk every item in `new_feature_doc_expectations` and `bootstrap_quirk_policy`. Tag push triggers `.github/workflows/release.yml`, which creates the GitHub Release automatically — do not create the release manually.
+
+Version is sourced from `package.json`; changelog from `CHANGELOG.md`; user-facing docs from `README.md`.
+
+---
+
+## Handoff expectations
+
+A fresh session picking up OCP work should read, in order:
+
+1. This file (`AGENTS.md`).
+2. `ALIGNMENT.md` — constitution; non-optional.
+3. `CLAUDE.md` — tool-specific instructions and release_kit overlay.
+4. `docs/adr/` — most recent ADRs first; they explain why the current structure exists.
+5. Any active plan under `docs/superpowers/plans/` (excluding `shipped/` which is the archive).
+6. `~/.cc-rules/memory/auto/MEMORY.md` — cross-machine memory index.
+
+Only after these should the session touch code.

ALIGNMENT.md

@@ -0,0 +1,91 @@
+# OCP Alignment Constitution
+
+**Status:** Active. This document is the supreme source of truth for OCP scope decisions. Conflicts with other documents (README, issues, prior commit messages) resolve in favor of this file.
+
+---
+
+## Core Principle
+
+OCP (Open Claude Proxy) is a **proxy layer** for the Claude Code CLI. It forwards, observes, and multiplexes the traffic that `cli.js` already emits. It is **not** an extension layer. If `cli.js` does not perform a given operation, or performs it differently, OCP does not invent one.
+
+---
+
+## Rules
+
+1. **Rule 1 (Grep First).** Before adding, renaming, or changing any endpoint, header, parameter, or response shape, the author must `grep` the reference `cli.js` and record the exact line numbers in the commit message and PR body. An absent grep hit is itself a finding and must be declared.
+
+2. **Rule 2 (No Invention).** OCP must not introduce endpoints, headers, request fields, or response fields that are not present in `cli.js`. Speculative "Claude Code probably uses X" statements are prohibited. If the behavior is not observable in `cli.js`, the feature is out of scope.
+
+3. **Rule 3 (Match the Implementation).** When `cli.js` does perform a given operation, OCP must match it byte-for-byte on the wire: same path, same method, same headers (including casing and ordering constraints), same body schema, same auth scheme. Deviations require an explicit, reviewed exception recorded in this file.
+
+4. **Rule 4 (Unalignable Features Are Deleted).** Any existing OCP feature that cannot be traced to a concrete `cli.js` reference is deleted. There is no "grandfathering" and no "keep it disabled." The policy is removal, not deprecation. See the Unalignable Policy section below.
+
+5. **Rule 5 (Cite Line Numbers in Commits).** Every commit that touches `server.mjs` must reference `cli.js` by line number or function name in the form `cli.js:NNNN` or `cli.js vE4 <functionName>`. Commits asserting "Claude Code uses X" without such a citation are blocked by CI and must be reverted on detection.
+
+---
+
+## Golden Reference: `cli.js`
+
+`cli.js` is the Claude Code CLI JavaScript bundle shipped inside the `@anthropic-ai/claude-code` npm package. It is the single source of truth for "what Claude Code actually does."
+
+### Canonical paths per machine
+
+| Machine / environment | Path |
+| --- | --- |
+| macOS (npm global) | `/usr/local/lib/node_modules/@anthropic-ai/claude-code/cli.js` |
+| macOS (nvm) | `~/.nvm/versions/node/*/lib/node_modules/@anthropic-ai/claude-code/cli.js` |
+| Linux (npm global) | `/usr/lib/node_modules/@anthropic-ai/claude-code/cli.js` |
+| Linux (OCI opc user) | `~/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js` |
+| Windows (npm global) | `%APPDATA%\npm\node_modules\@anthropic-ai\claude-code\cli.js` |
+| Raspberry Pi (nvm) | `~/.nvm/versions/node/*/lib/node_modules/@anthropic-ai/claude-code/cli.js` |
+
+### Current audit pin
+
+- **Claude Code version under audit:** `2.1.89`
+- **`cli.js` SHA-256:** `a9950ef6407fdc750bddb673852485500387e524a99d42385cb81e7d17128e01`
+- **Audit date:** `2026-04-20`
+- **Auditor:** `project maintainer`
+
+The audit pin is updated once per year (see Annual Alignment Audit) and whenever a drift incident forces a re-verification.
+
+---
+
+## Historical Lesson: The 2026-04-11 Drift
+
+On 2026-04-11, commit `b87992f` ("fix: use dedicated /api/oauth/usage endpoint for reliable plan data") was merged. The commit message asserted that `/api/oauth/usage` was "the dedicated usage endpoint that Claude Code CLI uses."
+
+**This assertion was false.** The string `/api/oauth/usage` does not appear in `cli.js` at any version shipped up to that date. The endpoint was fabricated by an LLM-assisted authoring pass that generalized from adjacent OAuth paths without verifying against `cli.js`. A follow-up commit `cb6c2a8` ("fallback to stale cache on usage API 429 + extend cache to 15min") compounded the error by caching the fabricated response to hide the 4xx failures.
+
+**Impact:** The `/usage` progress bar in the dashboard was broken for nine days (2026-04-11 through 2026-04-20) before the drift was isolated.
+
+**Root cause:** LLM hallucination accepted without `grep cli.js` verification, compounded by the absence of a CI blacklist and the absence of this constitution.
+
+**Fix commit:** `fd7973a` (PR #21 — restored header-based `/usage`); follow-up `01e260c` (PR #24 — OAuth Bearer header correction)
+
+**Lesson codified:** Rules 1, 2, and 5 of this document; the CI blacklist in `.github/workflows/alignment.yml`; and the PR template evidence section exist to make the 2026-04-11 drift structurally impossible to repeat.
+
+---
+
+## Unalignable Policy
+
+A feature is **unalignable** if, after a good-faith search, it cannot be mapped to a specific `cli.js` line range or function.
+
+- Unalignable features are **deleted**, not disabled, not feature-flagged, not deprecated.
+- Deletion is the default outcome of an alignment audit finding. The burden of proof is on the feature, not on the auditor.
+- A deletion PR does not require user-facing deprecation notice, because the feature was never legitimately in scope.
+- If a user workflow depended on an unalignable feature, the correct remediation is to upstream the behavior into `cli.js` or to move it out of OCP into a separate tool. OCP does not retain it.
+
+---
+
+## Annual Alignment Audit
+
+- **Date:** 11 April each year (the anniversary of the `b87992f` drift).
+- **Scope:** Diff the current `cli.js` against the pinned SHA-256 in the Golden Reference section. For every network call in `server.mjs`, re-verify that the corresponding `cli.js` reference still exists at the cited line numbers (adjust citations if line numbers shifted across Claude Code versions).
+- **Output:** A signed audit note committed to `docs/alignment-audits/YYYY-04-11.md`, updating the pin.
+- **Failure mode:** Any audit finding that cannot be reconciled triggers an immediate deletion PR per the Unalignable Policy.
+
+---
+
+## Amendment Procedure
+
+This constitution is amended only by a PR that (a) cites the evidence motivating the amendment, (b) is reviewed by an independent reviewer per CC Iron Rule 10, and (c) updates the Historical Lesson section if the amendment was driven by an incident. Amendments never retroactively legitimize previously unalignable features.

CHANGELOG.md

@@ -0,0 +1,179 @@
+# Changelog
+
+## v3.16.2 — 2026-05-12
+
+### Fixes — corrects v3.16.1
+
+The v3.16.1 fix was directionally correct (plugin now reads env first, falls back to a hardcoded default) but **the narrative and the hardcoded default were both wrong**.
+
+What v3.16.1 said: "OCP server moved to 3478 default in v3.14+; plugin lagged at 3456."
+What is actually true:
+- **OCP server source default has been `3456` since `593d0dc` (initial release) and has never changed.** Every line in `server.mjs`, `setup.mjs`, and the `ocp` CLI still uses `3456` as the documented and code-level default.
+- The single OCP installation observed on `3478` is the maintainer's Mac mini, whose plist was rewritten with `--port 3478` during a PR #71 dogfood smoke-test accident on 2026-05-08 (see `~/.cc-rules/memory/learnings/subagent_setup_mjs_prod_host_collision.md`). The plist drift was never reconciled back to source default, and v3.16.1 incorrectly canonised the post-accident value as if it had been a release decision.
+
+This release:
+- Restores the plugin fallback to `http://127.0.0.1:3456` to match server source default.
+- Updates `openclaw.plugin.json` `configSchema.proxyUrl.default` back to `3456`.
+- Restores README §"Environment Variables" `CLAUDE_PROXY_PORT` default to `3456`.
+- Plugin reads `OCP_PROXY_URL` env (full URL) first, then `CLAUDE_PROXY_PORT` env (port only), then falls back to `3456`. Hosts whose OCP plist injects a non-default port must also inject the same `CLAUDE_PROXY_PORT` into the OpenClaw plist for the plugin to follow.
+- Maintainer's Mac mini plist was reverted from `3478` to `3456` as part of this release deploy (no source change reflects this; it was a one-host correction).
+
+### Governance
+
+- No `cli.js` citation needed (no `server.mjs` change). ALIGNMENT.md Rule 2 not engaged.
+
+## v3.16.1 — 2026-05-12 (superseded — narrative incorrect; see v3.16.2 erratum)
+
+### Fixes (as shipped — note erratum above)
+
+- **OCP plugin port lag** — `ocp-plugin/index.js` hard-coded `http://127.0.0.1:3456`. ~~While OCP server moved to 3478 in v3.14+,~~ **(corrected v3.16.2: no such move ever happened.)** The Mac mini's plist was on `3478` only as residue from a dogfood accident. Result: `/ocp` slash commands from the home Telegram bot returned "OCP error: fetch failed". v3.16.1 changed the plugin default to `3478` (wrong direction; v3.16.2 reverts to `3456`).
+
+### Governance
+
+- No `cli.js` citation needed (no `server.mjs` change). ALIGNMENT.md Rule 2 not engaged.
+
+## v3.16.0 — 2026-05-10
+
+### Features
+
+- **`ocp doctor --check oauth`** (PR #93) — fast path that runs only the OAuth check, skipping
+  version detection / from-version / git operations / models endpoint. ~50ms vs. full doctor's
+  ~200-500ms. Use cases: AI agent repair loops, post-`claude auth login` verify, quick health
+  gates. Help text in `cmd_doctor_help` now reflects working behaviour.
+- **`ocp update --rollback --gc`** — manually garbage-collect old upgrade snapshots.
+  Retention policy: keep last 5 snapshots OR snapshots newer than 30 days OR the single most
+  recent (always-keep safety net). `--dry-run` previews. Successful `ocp update` runs auto-GC
+  at the end of the full path; light path does not (no snapshot created there).
+
+### Behavior changes
+
+- After a successful cross-minor `ocp update`, the auto-GC emits `[gc] removed N old snapshots`
+  to stderr if any were collected. Safe to ignore; manual gc is `ocp update --rollback --gc`.
+
+### Governance
+
+- No `cli.js` citation needed (no `server.mjs` change). ALIGNMENT.md Rule 2 not engaged.
+- PR #93 (--check oauth) merged separately; this release bundles it with the GC feature.
+
+## v3.15.1 — 2026-05-10
+
+### Fixes
+
+- **doctor: dynamic `latest_version` from `origin/main:package.json`** — v3.15.0 doctor used a hard-coded `latest = "v3.14.0"` fallback, which made any v3.15.0+ install report `kind = upgrade` (against a stale value). `ocp update` would then attempt `git checkout v3.14.0` — a downgrade. Doctor now fetches `git -C ~/ocp show origin/main:package.json` to determine the actual latest version; on failure (offline, fresh clone with no remote), falls back to `currentVersion` so `kind = noop` instead of recommending a downgrade.
+
+## v3.15.0 — 2026-05-10
+
+### Features
+
+- **`ocp doctor`** — health & upgrade-readiness check; primary entry for AI-driven debugging.
+  `--json` mode emits a `next_action` with `ai_executable[]` for agents to run verbatim
+  and `human_required[]` for steps requiring the user (typically only OAuth).
+- **`ocp update` cross-version path** — for cross-minor jumps (e.g. v3.10 → v3.14),
+  `ocp update` now runs doctor → snapshot → `setup.mjs` (with the plist env-merge from
+  PR #90) → service restart → post-flight `/health` + `/v1/models` verification.
+  Same-patch updates retain the existing light path; users see no change for routine
+  patch bumps.
+- **`ocp update --rollback`** — restore the most recent (or specified) upgrade snapshot.
+  Snapshots are saved to `~/.ocp/upgrade-snapshot-<ISO-ts>/` and never auto-deleted.
+- **Fresh-install routing** — `ocp update` on installations < v3.4.0 routes to a fresh-install
+  flow (with `--yes` to skip confirmation; AI agents pass this). OAuth survives via Claude
+  Code's credential store; users do not re-OAuth unless their token was independently broken.
+- **AI prompt blocks in README** — §Installation, §Upgrading, and §Troubleshooting each
+  start with a copy-paste prompt for Claude Code / Cursor / Copilot, so users can drive
+  install / setup / upgrade through their existing AI assistant.
+
+### Behavior changes
+
+- `ocp update` may take 10–30s longer when a cross-minor jump triggers the full path
+  (snapshot + post-flight). Patch bumps are unchanged.
+- Pre-v3.4.0 installs are routed to fresh-install rather than failing silently or
+  half-migrating.
+
+### Governance
+
+- No `cli.js` citation needed (no `server.mjs` change). ALIGNMENT.md Rule 2 not engaged.
+- Depends on PR #90 (plist env merge bug fix; merged before this release).
+
+## v3.14.0 — 2026-05-10
+
+### Features (security hardening)
+
+- **Per-key session isolation** (PR #86, S1) — the `sessions` Map in `server.mjs` is now keyed by `${keyName}|${conversationId}` instead of bare `conversationId`. Before this fix, two clients using distinct API keys but the same `session_id` value (e.g. both defaulting to `"default"`) would share the same `cli.js` subprocess and conversation history, creating a cross-tenant leak path. Post-fix each (key, session) pair is isolated end-to-end, extending the per-key cache isolation shipped in v3.13.0 D1 to the session layer.
+- **On-disk credential file modes 0700/0600** (PR #87, S2) — `setup.mjs` now creates `~/.ocp` at mode 0700 and both `admin-key` and `ocp.db` at mode 0600. An idempotent `reconcileFileModes()` call in `server.mjs` startup tightens any existing installation to these modes automatically on every launch, so existing prod boxes fix themselves without manual `chmod`. Before this fix, all three files were created at the process's default umask (typically world-readable 0644 / 0755), leaving plaintext credentials readable by other local users.
+- **`/api/usage` default scope = self; admin all-keys requires `?all=true`** (PR #88, S3) — the usage endpoint now applies a least-privilege default: anonymous callers receive only their own rows, non-admin authenticated callers receive only their own rows, and admin callers receive only their own rows unless they explicitly pass `?all=true`. When `?all=true` is used, an audit log line is emitted. Before this fix, any admin-token holder could silently enumerate usage data for every key on the server.
+
+### Behavior changes
+
+- **Breaking change for admin tooling**: `/api/usage` no longer returns all-keys data by default. Existing cron jobs, dashboards, or scripts that rely on the admin token seeing all-keys output must add `?all=true` to their request URL after upgrading to v3.14.0.
+- **File mode reconcile at server startup** logs a one-line notice per path when mode is tightened (e.g. `[security] tightened ~/.ocp/ocp.db → 0600`). No action is required from the operator; the reconcile is idempotent and silent when modes are already correct.
+- **`sessions` Map key is now `${keyName}|${conversationId}` internally.** No client-visible wire change — the `session_id` field in request/response is unchanged.
+
+### Verification
+
+- Stress-test pass: 11/11 phases including S1/S2/S3 security regression checks (Phase E, I, J). 35-minute sustained run, 60 calls, 0 errors, 0 timeouts. RSS dropped 51→47 MB across the window. Per-key cache isolation, singleflight, cache_control bypass, quota enforcement, file-mode reconcile, and scope guard against escalation all verified against running code.
+
+### Governance
+
+- All three PRs (#86, #87, #88) include the explicit `cli.js`-citation-not-applicable disclaimer (per PR #75 pattern) since they are OCP-internal access-control, session-state, and file-permission changes with no corresponding `cli.js` operation to cite.
+
+### No new env vars / no public API surface change beyond the documented breaking change
+
+This release adds no new env vars or endpoints. The only externally visible change is the `/api/usage` scope guard (breaking for admin all-keys consumers; see Behavior changes above).
+
+## v3.13.0 — 2026-05-07
+
+### Features (cache layer hardening)
+
+- **Per-key cache isolation** (D1) — the cache key now includes the API key id, so distinct keys never share cache entries. Anonymous/unauthenticated callers share one `anon` pool. Hash format upgraded to `v2`; legacy v1-format rows orphan and are reaped by the existing TTL cleanup interval (no migration script).
+- **`cache_control` bypass** (D2) — when a request carries an Anthropic `cache_control` annotation (top-level or nested in a content array), OCP skips its own cache entirely. The caller is using Anthropic-side prompt caching deliberately, and OCP must not interfere. A `cache_skipped{reason: cache_control_present}` log line is emitted on bypass.
+- **Chunked stream replay** (D3) — when a streaming request hits the cache, the cached content is now emitted as multiple SSE chunks (80 codepoints/chunk, codepoint-safe via `Array.from()`) instead of a single large delta. Multibyte characters (CJK / emoji) stay intact.
+- **Singleflight stampede protection** (D4) — concurrent identical cache-miss requests now share one upstream `cli.js` spawn instead of spawning N processes. Followers receive byte-identical responses to what the leader returns. All-or-nothing failure semantics: if the leader errors, all followers receive the same error. Streaming-path singleflight is explicitly out of scope (TODO left for follow-up).
+
+### Behavior changes
+
+- `/cache/stats` response now includes additive fields `inflight` and `requesters` (current in-flight singleflight entries and total waiting callers). Existing fields `entries`, `totalHits`, `sizeBytes` are preserved unchanged.
+
+### Governance
+
+- New ADR [`docs/adr/0005-no-multi-provider.md`](docs/adr/0005-no-multi-provider.md): OCP stays single-provider (Anthropic via `cli.js` spawn). Multi-provider gateway refactor explicitly out of scope; cache improvements are explicitly in scope.
+- Design spec for this release: [`docs/superpowers/specs/2026-05-07-cache-upgrade-design.md`](docs/superpowers/specs/2026-05-07-cache-upgrade-design.md).
+
+### No new env vars / no public API surface change
+
+This release adds no new env vars or endpoints. All four improvements are internal correctness/concurrency upgrades to the existing `CLAUDE_CACHE_TTL`-gated cache layer. No client-observable wire shape change.
+
+## v3.12.0 — 2026-04-25
+
+### Features
+
+- **Streaming heartbeat** — opt-in SSE comment frame (`: keepalive\n\n`) emitted during silent windows on the streaming response. Controlled by `CLAUDE_HEARTBEAT_INTERVAL` env var (ms; `0` = disabled, default). Covers both pre-first-byte and mid-stream tool-use pauses. Addresses #47. See [design doc](docs/superpowers/specs/2026-04-25-47-sse-heartbeat-design.md).
+- **`X-Accel-Buffering: no`** response header added to SSE responses so heartbeats survive nginx/Cloudflare default buffering.
+
+### Behavior changes
+
+- SSE headers are now sent immediately after the claude CLI spawns successfully, not on first stdout byte. The rare "spawn succeeded but subprocess died before any byte" path now closes the SSE stream cleanly rather than returning a JSON error.
+
+### Config additions
+
+| Variable | Default | Description |
+|---|---|---|
+| `CLAUDE_HEARTBEAT_INTERVAL` | `0` (disabled) | Interval in ms for SSE keepalive comment frames on streaming path. Resets on every real frame. |
+
+## v3.11.1 — 2026-04-21
+
+### Fixes
+- Concurrency slot leak on subprocess timeout (#37). The request-timeout handler called `proc.kill("SIGTERM")` without decrementing `stats.activeRequests`. A subprocess stuck in a syscall that ignored SIGTERM would hold its slot until (or beyond) the 5s SIGKILL escalation actually reaped it. Slot release is now wired to `proc.once("exit", cleanup)` so every termination path — normal close, error, SIGTERM, SIGKILL — releases the slot exactly once.
+
+## v3.11.0 — 2026-04-20
+
+### Features
+- `ocp update` now automatically syncs OpenClaw's registry with the latest models (scripts/sync-openclaw.mjs)
+- Server logs warn if OpenClaw registry drifts from models.json
+
+### Refactor
+- models.json is now the single source of truth for model list
+- server.mjs and setup.mjs derive MODEL_MAP/MODELS from models.json
+- Adding a new model is now a one-file edit
+
+### Fixes
+- OpenClaw's model dropdown now shows all 4 current models (opus-4-7, opus-4-6, sonnet-4-6, haiku-4.5) on existing installs after `ocp update`. Previously setup.mjs only wrote the registry at install time.

CLAUDE.md

@@ -0,0 +1,94 @@
+@AGENTS.md
+@~/.cc-rules/AGENTS.md
+
+# OCP Project Session Instructions
+
+> **WARNING — READ BEFORE WRITING ANY CODE IN THIS REPO**
+>
+> Before touching `server.mjs` or any network-facing surface, read [`./ALIGNMENT.md`](./ALIGNMENT.md) in full. The constitution is binding. Non-compliant commits are reverted.
+
+---
+
+## Before starting any task
+
+1. Read `./ALIGNMENT.md`. Internalize the five Rules and the 2026-04-11 drift lesson.
+2. Run `/dev-start <task description>` to get a pre-flight plan that incorporates the iron rules, `SKILL_ROUTING.md`, this file, and `ALIGNMENT.md`.
+3. If the task touches `server.mjs`, locate the corresponding `cli.js` reference **before** drafting any code. No code is written ahead of the `grep cli.js` evidence.
+
+---
+
+## Hard requirements for `server.mjs` changes
+
+Every PR that modifies `server.mjs` must satisfy all three of the following. A PR missing any one of them is blocked from merge.
+
+1. **`cli.js` citation.** The commit message and PR body declare the corresponding `cli.js` function name and line number range, using the format `cli.js:NNNN` or `cli.js vE4 <functionName>`. If `cli.js` does not perform the operation, the PR must state this explicitly and justify scope under `ALIGNMENT.md` Rule 2 (in practice, this almost always means the PR should be closed).
+2. **CI blacklist pass.** The `alignment.yml` workflow must pass. The workflow greps `server.mjs` for known-hallucinated tokens (currently blocking `api.anthropic.com/api/oauth/usage`) and fails the build on any hit. New tokens are added via PR amendment to `alignment.yml`; removing entries requires an `ALIGNMENT.md` amendment PR. Do not suppress the workflow.
+3. **Independent reviewer (Iron Rule 10).** The implementation author may not self-approve. A separate reviewer — human or a subagent spawned with a fresh context — must read the diff, verify the `cli.js` citation by opening `cli.js` at the cited lines, and explicitly approve. A review comment that does not confirm the `cli.js` citation was checked is not a valid approval.
+
+---
+
+## Iron rules in force
+
+This repo operates under the CC Development Iron Rules (CC 开发铁律) v1.3. Three rules are load-bearing for OCP work:
+
+- **Iron Rule 10 (Code Review).** Every implementation phase has an independent reviewer. Self-review does not count. See `server.mjs` hard requirement #3 above.
+- **Iron Rule 11 (Incremental Diff Review).** Non-trivial work is split into the minimum reviewable unit — one PR per layer per severity. `ALIGNMENT.md`, `CLAUDE.md`, the PR template, and the CI workflow are therefore shipped as the same constitutional PR (they are one layer: governance), but any subsequent `server.mjs` remediation lands as its own PR.
+- **Iron Rule 12 (Pre-Brainstorm Prior-Art Search).** Before proposing any new endpoint or header, search GitHub, Anthropic docs, and the `cli.js` bundle. For OCP specifically, the `cli.js` grep is the decisive search: if it does not hit, Rule 2 of the constitution applies.
+
+The full iron rules are at `~/.claude/CC_DEV_IRON_RULES.md` (symlinked from the cc-rules repo on the maintainer's workstations). Load them into session context with `/cc-rules` when needed.
+
+---
+
+## Skills relevant to this repo
+
+- `/dev-start` — pre-flight planning, always first.
+- `/cc-rules` — load the iron rules into context.
+- `/agent-dispatch` — pick the correct model (opus for design and review, sonnet for straightforward edits, haiku for mechanical chores) before spawning any subagent.
+- `/cc-mem search <keyword>` — look up cross-machine memory for prior decisions, especially prior drift incidents.
+
+---
+
+## Commit message conventions
+
+- Subject line uses Conventional Commits (`fix:`, `feat:`, `docs:`, `refactor:`, `chore:`).
+- Any assertion of the form "Claude Code uses X" or "cli.js uses X" in the body must be immediately followed by a citation in the form `cli.js:NNNN` or `cli.js vE4 <functionName>`. CI performs a soft check for this pattern on all commits in the PR.
+- Co-author trailer is required for LLM-assisted commits (`Co-Authored-By: Claude <model> <noreply@anthropic.com>`).
+
+---
+
+## Project-level escalation
+
+If a design decision cannot be resolved by reference to `cli.js` and `ALIGNMENT.md`, escalate to the project maintainer via `/cc-chat` rather than guessing. Silent guessing is what produced the 2026-04-11 drift.
+
+---
+
+## Release kit overlay (CC 开发铁律 第五律 5.5)
+
+This project's overlay per iron rule v1.4's 5.5. Machine-checkable declaration.
+
+```yaml
+release_kit:
+  version_source: package.json
+  changelog: CHANGELOG.md
+  release_channel:
+    type: github-release
+    tag_format: v{semver}
+    auto_create_on_tag_push: true   # via .github/workflows/release.yml
+  docs_source: README.md
+  resource_lists:
+    - name: Available Models table
+      location: README.md § "Available Models"
+      source_of_truth: models.json
+    - name: API Endpoints table
+      location: README.md § "API Endpoints"
+    - name: Environment Variables table
+      location: README.md § "Environment Variables"
+  new_feature_doc_expectations:
+    - new CLI subcommand → README § "All Commands" + usage example
+    - new env var → README § "Environment Variables" table
+    - new auto-sync / hook → dedicated §, must document trigger + manual invocation + opt-out + any bootstrap quirk
+    - new endpoint → README § "API Endpoints" table + any relevant Config/Troubleshooting §
+    - new file / SPOT / schema → Architecture or contributor § with link
+  bootstrap_quirk_policy:
+    - any one-time migration quirk → README § "Troubleshooting"
+```

Dockerfile

@@ -1,14 +0,0 @@
-FROM node:20-alpine
-
-WORKDIR /app
-
-COPY server.mjs ./
-COPY setup.mjs ./
-COPY package.json ./
-
-ENV CLAUDE_SESSION_TOKEN="" \
-    CLAUDE_COOKIES=""
-
-EXPOSE 3456
-
-CMD ["node", "server.mjs"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tao Deng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dashboard.html

@@ -0,0 +1,266 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>OCP Dashboard</title>
+<style>
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; background: #0f172a; color: #e2e8f0; padding: 1.5rem; }
+  h1 { font-size: 1.5rem; margin-bottom: 1rem; color: #38bdf8; }
+  h2 { font-size: 1.1rem; margin: 1.5rem 0 0.5rem; color: #94a3b8; }
+  .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 1rem; margin-bottom: 1.5rem; }
+  .card { background: #1e293b; border-radius: 8px; padding: 1rem; }
+  .card .label { font-size: 0.75rem; color: #64748b; text-transform: uppercase; }
+  .card .value { font-size: 1.5rem; font-weight: 700; margin-top: 0.25rem; }
+  .card .sub { font-size: 0.8rem; color: #94a3b8; margin-top: 0.25rem; }
+  table { width: 100%; border-collapse: collapse; margin-top: 0.5rem; }
+  th, td { text-align: left; padding: 0.5rem 0.75rem; border-bottom: 1px solid #334155; font-size: 0.85rem; }
+  th { color: #64748b; font-weight: 600; }
+  .tag { display: inline-block; padding: 2px 8px; border-radius: 4px; font-size: 0.75rem; }
+  .tag-ok { background: #065f46; color: #6ee7b7; }
+  .tag-err { background: #7f1d1d; color: #fca5a5; }
+  .btn { background: #2563eb; color: white; border: none; padding: 0.5rem 1rem; border-radius: 6px; cursor: pointer; font-size: 0.85rem; }
+  .btn:hover { background: #1d4ed8; }
+  .btn-sm { padding: 0.25rem 0.5rem; font-size: 0.75rem; }
+  .btn-danger { background: #dc2626; }
+  .btn-danger:hover { background: #b91c1c; }
+  input { background: #1e293b; border: 1px solid #334155; color: #e2e8f0; padding: 0.4rem 0.75rem; border-radius: 6px; font-size: 0.85rem; }
+  .flex { display: flex; gap: 0.5rem; align-items: center; }
+  .mono { font-family: "SF Mono", "Fira Code", monospace; font-size: 0.8rem; }
+  .bar-bg { background: #334155; border-radius: 4px; height: 8px; overflow: hidden; margin-top: 0.5rem; }
+  .bar-fill { height: 100%; border-radius: 4px; transition: width 0.5s; }
+  .bar-blue { background: #3b82f6; }
+  .bar-amber { background: #f59e0b; }
+  .bar-red { background: #ef4444; }
+  #refresh-indicator { font-size: 0.75rem; color: #475569; }
+  .section { margin-bottom: 2rem; }
+</style>
+</head>
+<body>
+
+<div class="flex" style="justify-content: space-between; margin-bottom: 1.5rem;">
+  <h1>OCP Dashboard</h1>
+  <div class="flex">
+    <span id="refresh-indicator"></span>
+    <button class="btn btn-sm" onclick="refreshAll()">Refresh</button>
+  </div>
+</div>
+
+<div class="grid" id="status-cards"></div>
+
+<div class="section">
+  <h2>Plan Usage</h2>
+  <div class="grid" id="plan-cards"></div>
+</div>
+
+<div class="section">
+  <div class="flex" style="justify-content: space-between; align-items: center;">
+    <h2 style="margin: 0;">Usage by Key</h2>
+    <label id="usage-scope-toggle" class="flex" style="display:none; gap: 0.4rem; font-size: 0.8rem; color: #94a3b8; cursor: pointer;">
+      <input type="checkbox" id="usage-show-all" style="cursor: pointer;">
+      <span>Show all keys</span>
+    </label>
+  </div>
+  <table id="key-usage-table">
+    <thead><tr><th>Key</th><th>Requests</th><th>OK</th><th>Err</th><th>Avg Time</th><th>Last Request</th></tr></thead>
+    <tbody></tbody>
+  </table>
+</div>
+
+<div class="section" id="key-mgmt-section" style="display:none">
+  <h2>API Keys</h2>
+  <div class="flex" style="margin-bottom: 0.75rem;">
+    <input type="text" id="new-key-name" placeholder="Key name (e.g. wife-laptop)">
+    <button class="btn btn-sm" onclick="addKey()">Create Key</button>
+  </div>
+  <table id="keys-table">
+    <thead><tr><th>Name</th><th>Key</th><th>Created</th><th>Status</th><th></th></tr></thead>
+    <tbody></tbody>
+  </table>
+</div>
+
+<div class="section">
+  <h2>Recent Requests</h2>
+  <table id="recent-table">
+    <thead><tr><th>Time</th><th>Key</th><th>Model</th><th>Prompt</th><th>Response</th><th>Time</th><th>Status</th></tr></thead>
+    <tbody></tbody>
+  </table>
+</div>
+
+<script>
+const BASE = window.location.origin;
+const headers = {};
+const urlToken = new URLSearchParams(window.location.search).get("token");
+const storedToken = urlToken || localStorage.getItem("ocp_token");
+if (urlToken) { localStorage.setItem("ocp_token", urlToken); history.replaceState(null, "", "/dashboard"); }
+if (storedToken) headers["Authorization"] = `Bearer ${storedToken}`;
+
+async function api(path) {
+  const resp = await fetch(BASE + path, { headers });
+  if (resp.status === 401 || resp.status === 403) {
+    const token = prompt("Enter your OCP admin key:");
+    if (token) {
+      localStorage.setItem("ocp_token", token);
+      headers["Authorization"] = `Bearer ${token}`;
+      return api(path);
+    }
+  }
+  return resp.json();
+}
+
+async function apiPost(path, body) {
+  const resp = await fetch(BASE + path, {
+    method: "POST", headers: { ...headers, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return resp.json();
+}
+
+async function apiDelete(path) {
+  const resp = await fetch(BASE + path, { method: "DELETE", headers });
+  return resp.json();
+}
+
+function fmtTime(ms) {
+  if (!ms) return "-";
+  return ms > 1000 ? (ms/1000).toFixed(1) + "s" : Math.round(ms) + "ms";
+}
+
+function fmtChars(n) {
+  if (!n) return "-";
+  return n > 1000 ? (n/1000).toFixed(0) + "K" : String(n);
+}
+
+function barColor(pct) {
+  if (pct >= 80) return "bar-red";
+  if (pct >= 50) return "bar-amber";
+  return "bar-blue";
+}
+
+async function refreshStatus() {
+  const data = await api("/status");
+  const p = data.proxy || {};
+  const r = data.requests || {};
+
+  document.getElementById("status-cards").innerHTML = `
+    <div class="card"><div class="label">Status</div><div class="value"><span class="tag ${p.status === 'ok' ? 'tag-ok' : 'tag-err'}">${p.status || '?'}</span></div><div class="sub">v${p.version || '?'}</div></div>
+    <div class="card"><div class="label">Uptime</div><div class="value">${p.uptime || '?'}</div></div>
+    <div class="card"><div class="label">Requests</div><div class="value">${r.total || 0}</div><div class="sub">${r.active || 0} active</div></div>
+    <div class="card"><div class="label">Errors</div><div class="value">${r.errors || 0}</div><div class="sub">${r.timeouts || 0} timeouts</div></div>
+    <div class="card"><div class="label">Sessions</div><div class="value">${p.activeSessions || 0}</div></div>
+  `;
+
+  const plan = data.plan;
+  if (plan && typeof plan === 'object' && !plan.error) {
+    const s = plan.currentSession || {};
+    const w = plan.weeklyLimits?.allModels || {};
+    const sPct = Math.round((s.utilization || 0) * 100);
+    const wPct = Math.round((w.utilization || 0) * 100);
+    document.getElementById("plan-cards").innerHTML = `
+      <div class="card">
+        <div class="label">Session (5h)</div>
+        <div class="value">${s.percent || '?'}</div>
+        <div class="bar-bg"><div class="bar-fill ${barColor(sPct)}" style="width:${sPct}%"></div></div>
+        <div class="sub">Resets in ${s.resetsIn || '?'}</div>
+      </div>
+      <div class="card">
+        <div class="label">Weekly (7d)</div>
+        <div class="value">${w.percent || '?'}</div>
+        <div class="bar-bg"><div class="bar-fill ${barColor(wPct)}" style="width:${wPct}%"></div></div>
+        <div class="sub">Resets in ${w.resetsIn || '?'}</div>
+      </div>
+    `;
+  }
+}
+
+async function refreshUsage() {
+  try {
+    const showAll = localStorage.getItem("ocp_usage_show_all") === "1";
+    const data = await api(showAll ? "/api/usage?all=true" : "/api/usage");
+    const tbody = document.querySelector("#key-usage-table tbody");
+    tbody.innerHTML = (data.byKey || []).map(k => `
+      <tr>
+        <td>${k.key_name}</td>
+        <td>${k.requests}</td>
+        <td>${k.successes}</td>
+        <td>${k.errors}</td>
+        <td>${fmtTime(k.avg_elapsed_ms)}</td>
+        <td class="mono">${k.last_request || '-'}</td>
+      </tr>
+    `).join("") || '<tr><td colspan="6" style="color:#475569">No usage data yet</td></tr>';
+
+    const rtbody = document.querySelector("#recent-table tbody");
+    rtbody.innerHTML = (data.recent || []).slice(0, 20).map(r => `
+      <tr>
+        <td class="mono">${r.created_at?.slice(11, 19) || '?'}</td>
+        <td>${r.key_name}</td>
+        <td>${r.model}</td>
+        <td>${fmtChars(r.prompt_chars)}</td>
+        <td>${fmtChars(r.response_chars)}</td>
+        <td>${fmtTime(r.elapsed_ms)}</td>
+        <td><span class="tag ${r.success ? 'tag-ok' : 'tag-err'}">${r.success ? 'ok' : 'err'}</span></td>
+      </tr>
+    `).join("") || '<tr><td colspan="7" style="color:#475569">No requests yet</td></tr>';
+  } catch(e) {
+    console.warn("Usage API not available:", e);
+  }
+}
+
+async function refreshKeys() {
+  try {
+    const data = await api("/api/keys");
+    document.getElementById("key-mgmt-section").style.display = "";
+    // Admin-only "Show all keys" toggle for /api/usage scope.
+    document.getElementById("usage-scope-toggle").style.display = "flex";
+    const tbody = document.querySelector("#keys-table tbody");
+    tbody.innerHTML = (data.keys || []).map(k => `
+      <tr>
+        <td>${k.name}</td>
+        <td class="mono">${k.keyPreview}</td>
+        <td class="mono">${k.created_at}</td>
+        <td><span class="tag ${k.revoked ? 'tag-err' : 'tag-ok'}">${k.revoked ? 'revoked' : 'active'}</span></td>
+        <td>${k.revoked ? '' : `<button class="btn btn-sm btn-danger" onclick="revokeKeyUI('${k.name}')">Revoke</button>`}</td>
+      </tr>
+    `).join("");
+  } catch(e) { /* not admin */ }
+}
+
+async function addKey() {
+  const name = document.getElementById("new-key-name").value.trim();
+  if (!name) return alert("Enter a key name");
+  const result = await apiPost("/api/keys", { name });
+  if (result.key) {
+    alert("New API Key (copy it now — you won't see it again):\n\n" + result.key);
+    document.getElementById("new-key-name").value = "";
+    refreshKeys();
+  }
+}
+
+async function revokeKeyUI(name) {
+  if (!confirm(`Revoke key "${name}"?`)) return;
+  await apiDelete(`/api/keys/${encodeURIComponent(name)}`);
+  refreshKeys();
+}
+
+async function refreshAll() {
+  document.getElementById("refresh-indicator").textContent = "Refreshing...";
+  await Promise.all([refreshStatus(), refreshUsage(), refreshKeys()]);
+  document.getElementById("refresh-indicator").textContent = `Updated ${new Date().toLocaleTimeString()}`;
+}
+
+// Wire "Show all keys" toggle (visibility gated to admin via refreshKeys()).
+(function setupUsageScopeToggle() {
+  const cb = document.getElementById("usage-show-all");
+  cb.checked = localStorage.getItem("ocp_usage_show_all") === "1";
+  cb.addEventListener("change", () => {
+    localStorage.setItem("ocp_usage_show_all", cb.checked ? "1" : "0");
+    refreshUsage();
+  });
+})();
+
+refreshAll();
+setInterval(refreshAll, 30000);
+</script>
+</body>
+</html>

docker-compose.yml

@@ -1,7 +0,0 @@
-services:
-  claude-proxy:
-    build: .
-    ports:
-      - "3456:3456"
-    env_file: .env
-    restart: unless-stopped

docs/adr/0002-alignment-constitution.md

@@ -0,0 +1,70 @@
+# 0002 — Alignment Constitution
+
+- **Date**: 2026-04-20
+- **Status**: Accepted
+- **Authors**: project maintainer (with AI drafting assistance)
+- **Related**: PR #20, commit 2853088; supersedes implicit "keep the proxy honest" discipline
+
+## Context
+
+On 2026-04-11 an OCP commit (`b87992f`, "fix: use dedicated `/api/oauth/usage` endpoint for reliable plan data") was merged. The commit asserted that `/api/oauth/usage` was "the dedicated usage endpoint that Claude Code CLI uses." The assertion was false: the string `/api/oauth/usage` does not appear anywhere in `cli.js`. The endpoint was fabricated by an LLM-assisted authoring pass generalizing from adjacent OAuth paths, without anyone running `grep` against `cli.js`.
+
+The hallucination was not an isolated slip. It persisted across nine days and two additional commits of compensation:
+
+- `cb6c2a8` extended the stale cache to 15 minutes and added a fallback path on HTTP 429 — a workaround that masked the fabricated endpoint's 4xx failures rather than investigating them.
+- The dashboard `/usage` progress bar was broken for the entire window (2026-04-11 through 2026-04-20).
+
+Root cause analysis identified three structural gaps:
+
+1. No binding rule that OCP must mirror `cli.js` behavior exactly. "Proxy-only" was aspirational, not enforced.
+2. No CI check that would fail builds containing known-hallucinated tokens.
+3. No reviewer gate that required the reviewer to verify the `cli.js` citation before approving.
+
+Without all three, the same class of drift was re-occurrence-probable rather than preventable.
+
+## Decision
+
+Adopt `ALIGNMENT.md` as the project constitution. It encodes five binding Rules:
+
+1. **Grep First** — before changing any endpoint/header/parameter/response shape, the author must `grep` `cli.js` and record the line numbers.
+2. **No Invention** — OCP must not introduce surface area not present in `cli.js`. Speculative "Claude Code probably uses X" statements are prohibited.
+3. **Match the Implementation** — where `cli.js` does perform the operation, OCP matches it byte-for-byte on the wire.
+4. **Unalignable Features Are Deleted** — features that cannot be traced to a `cli.js` reference are removed, not deprecated, not feature-flagged.
+5. **Cite Line Numbers in Commits** — every `server.mjs`-touching commit references `cli.js:NNNN` or `cli.js vE4 <functionName>`.
+
+Supporting mechanisms:
+
+- `CLAUDE.md` enshrines hard requirements for `server.mjs` PRs: `cli.js` citation, CI blacklist pass, independent reviewer who opens `cli.js` at the cited lines.
+- `.github/workflows/alignment.yml` greps `server.mjs` on every PR for the known-hallucinated token set (`api/oauth/usage`, `api/usage`, et al.) and fails the build on any hit.
+- `.github/PULL_REQUEST_TEMPLATE.md` makes the `cli.js` citation and the reviewer's cli.js-opened confirmation mandatory fields.
+- A bootstrap audit pin: Claude Code `2.1.89`, `cli.js` SHA-256 `a9950ef6407fdc750bddb673852485500387e524a99d42385cb81e7d17128e01`, auditor: project maintainer, date 2026-04-20. The pin is refreshed annually on 11 April (the drift anniversary) or on any re-verification event.
+- A documented Historical Lesson section in `ALIGNMENT.md` that names the drift commits by SHA, so the incident cannot be rewritten or quietly forgotten.
+
+## Consequences
+
+**Positive**
+
+- Every `server.mjs` change is now provably aligned to a specific `cli.js` line range before merge.
+- CI hard-fails any reintroduction of the specific hallucinated tokens; the failure mode is loud and immediate, not silent-and-cached.
+- The reviewer gate makes self-approval a policy violation, which structurally prevents the "fix my own hallucination" cycle that produced `cb6c2a8`.
+- The constitution becomes the foundation that later governance (iron rule v1.4, per-project release kit, cross-device dev system) builds on.
+
+**Negative**
+
+- `server.mjs` changes are meaningfully slower: the `grep` step and the reviewer's cli.js verification are real costs on every PR.
+- New contributors face a steeper ramp — they must read `ALIGNMENT.md` fully before their first server-side PR will pass review.
+- The CI blacklist is a moving target; as future drift patterns are discovered, the list grows, and each addition is governance work.
+
+**Follow-ons**
+
+- ADR 0003 (models.json SPOT) and ADR 0004 (OpenClaw auto-sync) both lean on the constitution's "one reviewable layer" structure.
+- Annual audit on 11 April is a recurring calendar obligation; failure to perform it is itself an alignment violation.
+- The `cli.js` bundle became opaque at v2.1.90 (binary packaging). Future audits require a different verification strategy — see Alternatives (b) below.
+
+## Alternatives considered
+
+**(a) Pure human discipline — no CI, no template, no ADR.** the maintainer would simply commit to grepping `cli.js` on every change, and reviewers would commit to verifying. Rejected: the 2026-04-11 drift already happened under exactly this regime. the maintainer is meticulous, and the drift still shipped. Social discipline alone cannot prevent LLM hallucination from slipping through, especially when the LLM's output is superficially plausible.
+
+**(b) Automatic `cli.js` diff on every PR.** A CI step that diffs `server.mjs`'s network surface against a parsed `cli.js` AST, blocking on any mismatch. Rejected as too fragile: `cli.js` v2.1.90+ ships as a minified/obfuscated binary, making AST-level grep invalid without an unofficial unbundling step. Any such pipeline becomes a maintenance burden on Anthropic's release cadence, and would routinely false-positive. The blacklist approach is lower-precision but dramatically more robust.
+
+**(c) Freeze OCP and fork a new `ocp-v2` from scratch.** Start over with alignment baked in from day one. Rejected: the existing user base depends on OCP, and the drift affected one endpoint, not the architecture. Retrofitting a constitution onto the existing repo is cheaper and preserves user trust.

docs/adr/0003-models-json-spot.md

@@ -0,0 +1,65 @@
+# 0003 — `models.json` as Single Source of Truth
+
+- **Date**: 2026-04-20
+- **Status**: Accepted
+- **Authors**: project maintainer (with AI drafting assistance)
+- **Related**: PR #30, commit c6f7850; precursor to ADR 0004
+
+## Context
+
+OCP's model catalog (the mapping from short aliases like `sonnet` and `opus` to full model IDs with context-window metadata) had organically drifted into three independent locations:
+
+1. `server.mjs` — `MODEL_MAP` and `MODELS` arrays, hardcoded at the top of the file. This was the runtime authority for `/v1/models` responses and alias resolution.
+2. `setup.mjs` — a separate `MODELS` constant, unchanged since the v3.0 era. Used only at first-install time to seed user config; by v3.10 it was stale and listed no Claude 4.x models at all.
+3. `~/.openclaw/openclaw.json` (on user machines) — written exactly once by `setup.mjs` during initial OCP install and never refreshed. A user who installed OCP in v3.0 and ran `ocp update` faithfully through v3.10 still had their OpenClaw config listing only three pre-Claude-4 models.
+
+By the v3.10.0 release, Opus 4.7 was correctly present in location (1) and absent from (2) and (3). The symptom reaching users: native Claude Code saw the new model immediately (because it queries `/v1/models` live from server.mjs), but OpenClaw users saw nothing new, and new-installers via `setup.mjs` got an incomplete initial config. Three distinct bug reports in the two weeks following v3.10.0.
+
+The drift was structural, not a bug in any one file. The files disagreed because there was no mechanism requiring them to agree.
+
+## Decision
+
+Extract all model metadata into `models.json` at the repo root. `server.mjs` and `setup.mjs` both read this file and derive their in-memory `MODEL_MAP`/`MODELS` structures from it. The file is committed to the repo; it is neither generated nor cached.
+
+Shape (summarized):
+
+- `models` — array of entries, each with `id` (full model ID), `alias` (short name), `context_window`, and flags where relevant.
+- `default_alias` — which alias resolves when the client sends an unknown or empty model.
+
+Migration approach:
+
+1. Hand-populate `models.json` from the v3.10.0 `server.mjs` `MODEL_MAP` values.
+2. Rewrite `server.mjs` to load and index `models.json` at startup.
+3. Rewrite `setup.mjs` to derive its `MODELS` constant from the same file.
+4. Verify byte-equivalence: the derived `MODEL_MAP` in v3.11.0 must be a byte-identical superset of the v3.10.0 hardcoded `MODEL_MAP`. This is checked by a one-shot comparison script during the refactor PR; no regression is permitted.
+
+Post-refactor, the contract for adding a model is: edit `models.json`, open a PR, reviewer sanity-checks the `id` string against Anthropic's model announcement, merge. No other file changes.
+
+## Consequences
+
+**Positive**
+
+- Single edit point eliminates the "updated one place, forgot the other" failure mode structurally.
+- `setup.mjs`'s latent staleness is repaired as a side effect — new-installers now get a fresh model list.
+- Opens the door to ADR 0004 (OpenClaw auto-sync), which requires a file-based SPOT to sync from.
+- The `models.json` format is stable, Markdown-friendly JSON, easy to diff in code review.
+
+**Negative**
+
+- One additional file to load at server startup (negligible cost, but now a startup dependency).
+- Schema drift risk: if anyone adds a new field to `models.json` that `server.mjs` or `setup.mjs` doesn't know about, the field is silently ignored. A future schema version tag may be warranted if the format grows.
+- `models.json` parse failure is now a fatal startup error; previously, bad model config required editing source. Consider this a feature, not a regression.
+
+**Follow-ons**
+
+- ADR 0004 (OpenClaw auto-sync) consumes `models.json` directly in `scripts/sync-openclaw.mjs`.
+- Future additions (per-model pricing, per-model capability flags, etc.) belong in `models.json`, not scattered back across `server.mjs`.
+- The README "Available Models" table is now derived documentation and its source of truth should be pinned to `models.json` in the release_kit overlay.
+
+## Alternatives considered
+
+**(a) Keep the three locations, enforce sync by manual review discipline.** A reviewer checklist item: "did you update all three places?" Rejected: the drift had already demonstrated that manual discipline is insufficient when the three files are in unrelated sections of the diff. Human reviewers routinely miss the third file. The 2026-04-11 alignment drift had already taught the project that discipline-only approaches fail.
+
+**(b) YAML with SOPS field-level encryption.** Some projects prefer YAML for multi-line string readability and use SOPS to encrypt sensitive fields. Rejected: OCP's model catalog contains no secrets — model IDs, aliases, and context windows are all public information published by Anthropic. YAML adds a parser dependency and SOPS adds a decryption step at startup, both for zero benefit. JSON is already native to Node, and `models.json` is easy to diff line-by-line in GitHub review UI.
+
+**(c) Fetch the model list live from Anthropic at server start.** Rejected: `cli.js` does not perform this operation, so per `ALIGNMENT.md` Rule 2 it is out of scope for OCP. Additionally, a live fetch introduces a startup-time network dependency and an availability coupling to Anthropic that OCP is explicitly designed to avoid (OCP is the gateway, not another consumer).

docs/adr/0004-openclaw-auto-sync.md

@@ -0,0 +1,67 @@
+# 0004 — OpenClaw Auto-Sync on `ocp update`
+
+- **Date**: 2026-04-20
+- **Status**: Accepted
+- **Authors**: project maintainer (with AI drafting assistance)
+- **Related**: PR #31, commit 5ef163a; builds on ADR 0003
+
+## Context
+
+v3.10.0 added Claude Opus 4.7 to OCP's `server.mjs` `MODEL_MAP`. Native Claude Code users and other IDE consumers (Cline, Aider, Cursor) saw the new model immediately, because every one of those clients queries `/v1/models` live at session start.
+
+OpenClaw is different. OpenClaw caches its provider/model list in `~/.openclaw/openclaw.json`, written exactly once during OCP's `setup.mjs` run, then treated as immutable until the user manually edits it. An OpenClaw user who installed OCP in, say, v3.7 and diligently ran `ocp update` through v3.10 still saw only the pre-Claude-4 model list. From their perspective, `ocp update` "did not do what it said."
+
+Within two weeks of v3.10.0, three separate bug reports surfaced, all with the same root cause: OpenClaw's cache was stale. Users tried the obvious workarounds (reinstall OpenClaw, edit the JSON by hand) and reported those as additional bugs when they misformatted the file.
+
+The underlying asymmetry: every other IDE integration is pull-based (asks OCP for models on demand); OpenClaw is push-based (was told once, caches forever). OCP had no mechanism for a subsequent push.
+
+Additionally, ADR 0003 had just landed `models.json` as the single source of truth — meaning the data a sync mechanism would need was now available in a machine-readable file rather than scattered across `server.mjs`.
+
+## Decision
+
+Add `scripts/sync-openclaw.mjs`, invoked automatically at the end of `ocp update`, plus a passive drift self-check in `server.mjs` startup. Design constraints:
+
+1. **Strictly scoped.** The script only touches two sub-trees of `~/.openclaw/openclaw.json`:
+   - `models.providers["claude-local"].models` — the provider's model list.
+   - `agents.defaults.models["claude-local/*"]` — per-agent defaults that reference claude-local models.
+   All other OpenClaw config (user-defined agents, non-claude-local providers, UI preferences) is left untouched.
+
+2. **Idempotent.** Running the script twice with the same `models.json` produces the same file both times — byte-identical. The script diffs before writing and no-ops if there is nothing to change.
+
+3. **Safe.** Before any write, the script creates a timestamped backup at `~/.openclaw/openclaw.json.bak.<ISO8601>`. The user can always roll back.
+
+4. **Non-fatal.** If `~/.openclaw/openclaw.json` is missing (OpenClaw not installed), malformed, or otherwise unwriteable, the script logs a single-line warning and exits 0. `ocp update` never fails because of sync.
+
+5. **Manually invocable.** `node scripts/sync-openclaw.mjs` runs the sync as a standalone operation, for users who want to trigger it without a full `ocp update`.
+
+6. **Passive drift self-check.** On server startup, `server.mjs` reads the `claude-local` model list from `openclaw.json` (if present) and compares against the models derived from `models.json`. Mismatches produce a single WARN log line — enough to alert the user without taking action. This is the "we noticed" signal; the fix is to run `ocp update`.
+
+Implementation source: the sync script reads the SPOT (`models.json`), produces the canonical claude-local model list, merges it into the OpenClaw config in the two scoped locations, writes atomically (write-to-temp then rename), and logs the diff.
+
+## Consequences
+
+**Positive**
+
+- Users get new models on the next `ocp update` with no manual action. The invariant OCP's update flow was advertising is now actually true.
+- Manual invocation remains available for users who want to sync without updating OCP itself (edge case, but cheap to support).
+- Passive self-check means even users who somehow skip `ocp update` receive a runtime heads-up instead of silent drift.
+- The script is short (under 150 lines) and testable in isolation.
+
+**Negative**
+
+- One-time bootstrap quirk: users upgrading from v3.10 → v3.11 have a cached `cmd_update` in their existing installation that does not yet invoke the new script. The first `ocp update` to v3.11 still misses the sync; the second `ocp update` (now running v3.11's code) performs it. This is documented in README § "Troubleshooting" per the release_kit `bootstrap_quirk_policy`.
+- A new script to maintain. If OpenClaw's config schema changes, this script needs updating. The strict-scope constraint bounds the maintenance surface.
+- Non-fatal-on-error means a broken `openclaw.json` silently stays broken from OCP's perspective. Accepted trade-off: `ocp update` failing because of a sibling tool's config would be worse.
+
+**Follow-ons**
+
+- If OpenClaw ever adopts live `/v1/models` polling upstream, this script becomes redundant and can be deleted per ADR 0002's Rule 4 (unalignable-to-upstream features are deleted).
+- Similar sync needs for future sibling tools would follow this pattern: separate script, strictly scoped, idempotent, non-fatal, invoked by `ocp update`.
+
+## Alternatives considered
+
+**(a) Modify OpenClaw itself to poll `/v1/models` live.** The "correct" fix at the architecture level. Rejected: OCP is a tenant in OpenClaw's plugin model, not its owner. Opening an upstream PR creates a cross-repo coordination dependency (review timeline, release timeline, version matrix) that leaves current OCP users broken for weeks or months. The sync script is something OCP can ship unilaterally and remove later if the upstream change lands.
+
+**(b) Re-run `setup.mjs` in full.** `setup.mjs` already knows how to write `openclaw.json` from scratch. Rejected: `setup.mjs` has many side effects beyond OpenClaw registration — it rewrites user shell rc files, regenerates systemd units, touches credential storage. It is explicitly not idempotent, and running it a second time on an already-configured system produces duplicate entries or regressions. The sync script's strict scope is the whole point; re-running `setup.mjs` would blow past it.
+
+**(c) Do nothing — tell users to manually edit `~/.openclaw/openclaw.json`.** Rejected for two reasons. First, UX: OCP's value proposition includes "`ocp update` keeps your toolchain current," and asking users to hand-edit a third party's JSON breaks that promise. Second, error rate: the three bug reports that motivated this ADR included two malformed-JSON follow-ups from users who tried the manual approach. A machine-written file is strictly safer than a hand-edited one.

docs/adr/0005-no-multi-provider.md

@@ -0,0 +1,79 @@
+# 0005 — OCP Stays Single-Provider; No Multi-Provider Refactor
+
+- **Date**: 2026-05-06
+- **Status**: Accepted
+- **Authors**: project maintainer (with AI advisory drafting)
+- **Related**: ADR 0002 (Alignment Constitution), ADR 0003 (`models.json` SPOT)
+
+## Context
+
+OCP's `server.mjs` reached 1667 lines and now provides response cache, per-key quota, session tracking, model-level stats, and SSE heartbeat — all targeting a single backend path: `spawn` the locally installed `cli.js` and let it transact with `api.anthropic.com`. This architecture is the source of OCP's only real differentiator: **`cli.js` behavior-level alignment** (session create-vs-resume semantics, tool_use id reuse, SSE quirks, etc.) — none of which a generic LLM gateway has, because none of them speak this protocol.
+
+The maintainer evaluated extending OCP to support OpenAI / Gemini / OpenRouter / Together / Groq / Ollama — i.e., turning OCP into a multi-provider gateway resembling Helicone, LiteLLM, OpenRouter, or Portkey. The motivation for that extension: reduce dependency on Anthropic, broaden OCP's commercial surface, and stop being grayscale-positioned (the `cli.js` spawn pattern depends on the local Pro/Max subscription, which Anthropic could fingerprint and disable).
+
+The honest engineering estimate for that extension:
+
+| Phase | Net New LOC | Calendar Time (part-time) |
+|---|---|---|
+| Provider abstraction + OpenAI | ~1230 + schema migration | 2 weeks |
+| Add Gemini | ~550 | +1.5 weeks |
+| OpenAI-compatible family (OpenRouter / Together / Groq) | ~300 | +1 week |
+| Tests, docs, hardening | — | +1.5 weeks |
+| **Multi-provider v1** | ~2080 | **~7 weeks focused** |
+
+That number is not the real cost. The real cost is **strategic**:
+
+1. **Loss of unique value.** `cli.js` behavior alignment is meaningless for OpenAI / Gemini / Ollama traffic. Going multi-provider means OCP's only moat applies to ~30% of its surface; the other 70% is generic gateway code already done better by Helicone / LiteLLM.
+
+2. **Hybrid architecture awkwardness.** A multi-provider OCP would have two paths: `spawn(cli.js)` for Claude (still grayscale, depends on Pro subscription), and direct API call for everyone else (clean, BYOK). Customers asking "what is OCP?" would hear two different answers depending on which model they pick. This is worse than either pure path.
+
+3. **Direct competition with funded incumbents.** Helicone (~$5M raised, YC W23), OpenRouter (~$1B valuation), LiteLLM (significant enterprise revenue), Portkey, Langfuse, Cloudflare AI Gateway — all already do multi-provider gateway with mature dashboards, audit logs, SOC2, and team features. OCP would enter that market 2+ years late with one engineer.
+
+4. **The grayscale problem isn't solved by adding providers.** As long as OCP keeps the `cli.js` spawn path for Anthropic, it remains grayscale for that path; adding OpenAI alongside doesn't make the Anthropic path any less dependent on a Pro/Max subscription that wasn't licensed for proxying.
+
+The maintainer's separate decision (recorded in personal notes, not this repo) is that **OCP itself will not be commercialized**; it will remain a personal power tool plus open-source contribution. Any commercial gateway work, if pursued, will start from a clean codebase with BYOK from day one — not from OCP.
+
+Given that, the multi-provider extension would buy OCP nothing: not a moat, not commercial readiness, not even meaningfully better personal utility (the maintainer overwhelmingly uses Claude).
+
+## Decision
+
+OCP stays single-provider. Specifically:
+
+1. **No new providers added to `server.mjs`.** The dispatch path remains `spawn(cli.js) → api.anthropic.com`. Pull requests that introduce a `providers/` directory or a model-to-provider router are declined on the basis of this ADR.
+
+2. **`models.json` schema stays Anthropic-only.** No `provider` field, no per-model cost/capability metadata that anticipates other providers. If non-Anthropic models ever need to be referenced (e.g., for OpenClaw provider list completeness), they live in a separate file or in OpenClaw's own config — not in OCP's SPOT.
+
+3. **Cache improvements are in scope.** The existing response cache (in `keys.mjs`: `cacheHash` / `getCachedResponse` / `setCachedResponse` / `clearCache`) is acceptable to upgrade with stream replay, stampede protection (singleflight), per-key isolation, and Anthropic `cache_control` awareness. These reinforce the single-provider position; they do not create provider-extension surface area.
+
+4. **Anthropic alignment work continues to be encouraged.** Anything that deepens `cli.js` behavior alignment — session lifetime, tool_use id semantics, SSE behavior, multi-account routing, model-tier observability — is the project's actual value and should be prioritized over generic-gateway features.
+
+5. **Commercial work, if pursued, starts elsewhere.** A separate repository, separate name, BYOK from day one, no `cli.js` spawn. That repo is out of scope for OCP and is not bound by this ADR.
+
+## Consequences
+
+**Positive**
+
+- Project scope stays bounded. The maintainer can keep evolving OCP at part-time pace without the multi-provider maintenance burden (every provider's API breaks at some point and demands attention).
+- The unique value (`cli.js` alignment) is preserved and continues to compound — every new alignment fix increases OCP's distance from generic gateways.
+- Future contributors reading the code see one architecture, not a hybrid; debugging stays tractable.
+- Decisions about commercialization are decoupled from OCP's technical evolution. OCP can stay grayscale-personal-tool indefinitely without that being a blocker for any future commercial product.
+
+**Negative**
+
+- OCP cannot serve any user who needs OpenAI / Gemini / local LLM access. Those users must route through a different gateway (Helicone, LiteLLM, OpenRouter) or call providers directly.
+- If Anthropic substantially changes `cli.js` (e.g., adds client attestation, removes the spawn-and-forward pattern, or migrates `claude` to a non-CLI form factor), OCP's core architecture breaks and there is no second backend to fall back to.
+- The maintainer must resist a recurring temptation: "while I'm in here, let me just add OpenAI." The whole point of this ADR is to make that temptation cost a documented amendment, not a quiet PR.
+
+**Neutral**
+
+- This ADR records a non-decision in code: nothing in `server.mjs` changes today. Its purpose is to make future contributors (including the maintainer) explain themselves before going against it. Per the project's PR template and Iron Rule 11, an amendment to this ADR is the gating step before any provider-extension PR.
+
+## Trigger conditions for revisiting this ADR
+
+This ADR should be revisited (and possibly amended or superseded) if any of the following occur:
+
+1. Anthropic ships a feature that breaks the `cli.js` spawn pattern OCP depends on, and the maintainer wants to keep OCP useful.
+2. The maintainer makes a deliberate decision to commercialize OCP (rather than start a separate codebase). This requires explicit re-scoping; "let me try" is not enough.
+3. A genuine user need emerges — e.g., the maintainer themselves starts using OpenAI / Gemini frequently from Claude Code workflows — that single-provider OCP cannot serve.
+
+In all three cases, the response is **first amend this ADR**, then write code. Order is not optional.

docs/adr/README.md

@@ -0,0 +1,38 @@
+# Architecture Decision Records
+
+This directory holds the OCP Architecture Decision Records (ADRs) — short documents that capture the **why** behind structural choices.
+
+Read these before proposing governance, SPOT (single-source-of-truth), or process changes.
+
+## Numbering
+
+ADRs start at `0002`. The first one (`0001`) was reserved for an early
+internal proposal that was superseded before publication; `0002` is
+deliberately the first published record so the archived `0001` slot
+remains a placeholder rather than being silently renumbered.
+
+New ADRs increment from the highest existing number. Filenames are
+`NNNN-<short-slug>.md`.
+
+## Index
+
+| ADR | Title | What it covers |
+|---|---|---|
+| [0002](0002-alignment-constitution.md) | Alignment Constitution | The `ALIGNMENT.md` constitution: why every `server.mjs` change requires `cli.js` citation + independent reviewer + CI blacklist pass. Background: the 2026-04-11 drift incident. |
+| [0003](0003-models-json-spot.md) | `models.json` as SPOT | Why model IDs / aliases / context windows live in a single JSON file (not duplicated in `server.mjs` and `setup.mjs` arrays). v3.11.0 refactor. |
+| [0004](0004-openclaw-auto-sync.md) | OpenClaw Auto-Sync | Why `scripts/sync-openclaw.mjs` runs on `ocp update`, what its scope boundary is (writes only `models.providers["claude-local"].models` and `agents.defaults.models["claude-local/*"]`), and the idempotency contract. |
+| [0005](0005-no-multi-provider.md) | No Multi-Provider | Why OCP stays single-provider (Anthropic-via-cli.js) and does not extend to OpenAI / Gemini / OpenRouter. Cost estimate: ~7 weeks for a v1 that buys neither moat nor commercial readiness. Separate commercial work starts in a separate repo. |
+
+## When to write a new ADR
+
+Open one whenever:
+
+- A structural rule is being added or changed (e.g., new SPOT, new boundary, new CI guardrail).
+- A decision encodes a lesson from an incident or drift.
+- A future contributor reading the code alone could plausibly undo or re-litigate the choice.
+
+Skip ADRs for routine implementation choices (algorithm pick, naming) — those belong in commit messages.
+
+## Format
+
+Keep ADRs short — Context / Decision / Consequences is the standard skeleton. Cite incidents, PRs, or commits where useful.

docs/superpowers/specs/2026-04-25-47-sse-heartbeat-design.md

@@ -0,0 +1,193 @@
+# Design: SSE Heartbeat on Streaming Path
+
+**Issue:** [#47](https://github.com/dtzp555-max/ocp/issues/47)
+**Date:** 2026-04-25
+**Status:** Draft (awaiting maintainer approval)
+**Target version:** v3.12.0 (minor — new opt-in feature + env var)
+
+---
+
+## Overview
+
+Add an opt-in idle-watchdog heartbeat to OCP's streaming response. When enabled, OCP emits an SSE comment frame (`: keepalive\n\n`) whenever the stream has been idle for a configurable interval. Timer resets on every real frame. Covers both pre-first-byte and mid-stream silent windows. Default **disabled**. Zero behavior change for existing deployments on upgrade.
+
+Companion tweak: `X-Accel-Buffering: no` response header added to both SSE header sites so heartbeats survive nginx-default proxy buffering.
+
+## Motivation
+
+Per [#47](https://github.com/dtzp555-max/ocp/issues/47): when `claude -p` takes a long time to respond (processing large contexts, or executing long tool calls that pause the token stream for 30s–5min), OCP emits no bytes to the downstream client for up to 600s. The caller cannot distinguish "slow but alive" from "hung." A recent incident reported 15 consecutive 600s silent waits cascading into a 2-hour downstream gateway outage.
+
+SSE heartbeats at the application layer let a caller observe liveness without OCP introducing any new client-killing timer.
+
+## Key decisions (with rationale)
+
+Six decisions were fixed during brainstorming. Each is presented as "decision → rationale" so future readers can judge whether a decision is still load-bearing.
+
+### D1. Coverage: whole-stream with idle-watchdog reset-on-byte
+
+A per-request timer starts when SSE headers are written and resets on every real `sendSSE()` call. Heartbeat fires only during genuine idle windows — never during healthy token bursts.
+
+**Rationale.** The `server.mjs:8-10` comment documents Claude tool-use pauses as "30s-5min pauses in the token stream." This means silent windows happen both pre-first-byte AND mid-stream. Covering only one of the two windows means re-opening this issue in three months when a different user reports the uncovered case. The reset-on-byte discipline is a ~2-LOC discipline (`clearTimeout` + `setTimeout` inside `sendSSE`) and is the standard "idle watchdog" pattern.
+
+### D2. Frame format: SSE comment (`: keepalive\n\n`)
+
+**Rationale.** Per SSE spec / MDN, lines starting with `:` are comments and MUST be ignored by conforming parsers. This is the maximally inert shape we can emit. Alternatives considered:
+- `event: ping` named event — Anthropic's own Messages API uses this, but on an OpenAI-compatible surface, downstream clients don't recognize that event name, so risk of client confusion is higher.
+- Empty-delta JSON chunk — parser-safe on OpenAI-compatible clients but burns an event id and is less observably "a heartbeat" in logs.
+
+The known risk with SSE comments is that some SDKs crash on empty comment frames (`openai-go` issue #556). The default-disabled posture (D3) mitigates this: users who opt in can also verify their client tolerates comments. If the comment format turns out to be broken in the wild for common OCP callers, we can add a second format behind `CLAUDE_HEARTBEAT_FORMAT` in a follow-up — **not in this PR**.
+
+### D3. Default disabled
+
+`CLAUDE_HEARTBEAT_INTERVAL=0` (meaning disabled) is the default when the env var is unset. Any positive integer enables at that ms interval.
+
+**Rationale.** Existing deployments see zero byte-shape change on upgrade. Users who have pingvvino's problem set the env var and get the fix. This is a reversible posture: once field evidence shows comment frames are safe across current OCP callers, a future minor can flip the default to `30000`.
+
+### D4. Header relocation: `ensureHeaders()` moves earlier
+
+Currently `ensureHeaders()` is invoked inside the `proc.stdout` handler, so SSE headers are written only on first byte from claude CLI. This PR moves the `ensureHeaders()` call to immediately after successful `spawn()` return.
+
+**Rationale.** You cannot emit SSE frames before sending SSE headers. For heartbeats to cover the pre-first-byte silent window (pingvvino's "processing large contexts" case), headers must be sent earlier. Behavioral consequence: the narrow "spawn succeeded but subprocess erroneously died before any byte" branch — currently a JSON error response — becomes an SSE error event + `[DONE]` + `res.end()`. Pre-spawn errors (before `spawn()`) still return JSON, unchanged. The affected path is rare (claude CLI either spawns or it doesn't).
+
+### D5. Transport-layer buffering hint: `X-Accel-Buffering: no`
+
+Added to both SSE response header sites (real-streaming `ensureHeaders()` and the cache-hit simulated-streaming header write).
+
+**Rationale.** nginx (and many LBs / Cloudflare) default to buffering proxied responses. Without this header, heartbeat bytes may accumulate in an upstream buffer and never reach the client, defeating the feature silently. This header is a nginx-specific hint; other stacks ignore it. 1 line per site, 2 sites total, indistinguishable-from-no-op for stacks that don't use it.
+
+### D6. Observability: single log line per affected request
+
+On the first heartbeat fire within a request, emit a structured log entry (`logEvent("info", "heartbeat_active", { session, intervalMs })`). No log spam for subsequent fires in the same request.
+
+**Rationale.** For a first-mover feature the question "did the heartbeat actually work for that hung request?" needs to be answerable from the existing `/logs` endpoint alone, without external tooling. One line per affected request gives proof-of-life without polluting the log stream during healthy traffic (where the timer resets and never fires).
+
+## Architecture
+
+Single-file change in `server.mjs`. One new helper plus small patches to existing sites.
+
+```
+startHeartbeat(res, intervalMs, sessionId) → { reset(), stop() }
+  if intervalMs <= 0: return no-op handle
+  internal: handle = setTimeout(intervalMs, onFire)
+  onFire():
+    res.write(": keepalive\n\n")
+    if !hasFired: logEvent("info", "heartbeat_active", { session, intervalMs }); hasFired = true
+    handle = setTimeout(intervalMs, onFire)
+  reset(): clearTimeout(handle); handle = setTimeout(intervalMs, onFire)
+  stop():  clearTimeout(handle); handle = null
+```
+
+Handle created once per streaming request. `sendSSE()` calls `heartbeat.reset()` before its `res.write()`. All exit paths call `heartbeat.stop()`.
+
+## Components and LOC budget
+
+| Location | Change | Est LOC |
+|---|---|---|
+| `server.mjs` env block | Parse `CLAUDE_HEARTBEAT_INTERVAL` | 1 |
+| `server.mjs` new `startHeartbeat()` function | Per spec above | 12 |
+| `server.mjs:565-579` `ensureHeaders()` | Add `"X-Accel-Buffering": "no"` to header object | 1 |
+| `server.mjs:~548-554` streaming entry | Move `ensureHeaders()` call to post-spawn; create heartbeat handle | 3 (net) |
+| `server.mjs:669` `sendSSE()` | Accept optional `hb` param; call `hb?.reset()` before `res.write()` | 2 |
+| `server.mjs` streaming exit hooks (proc 'close', proc 'error', req 'close') | Call `hb.stop()` | 3 |
+| `server.mjs:~610-611` pre-first-byte error branch | If headers sent, SSE error + `[DONE]` + `res.end()` instead of JSON | 3 |
+| `server.mjs:1171` cache-hit header write | Add `"X-Accel-Buffering": "no"` | 1 |
+| `README.md` env var table | One new row | 1 |
+| `README.md` new short section | "Streaming heartbeat" paragraph + nginx note | 5 |
+| `CHANGELOG.md` new v3.12.0 entry | Features + Config additions | 4 |
+| `package.json` + `ocp-plugin/package.json` + `ocp-plugin/openclaw.plugin.json` | Version bump 3.11.1 → 3.12.0 | 3 |
+
+**Estimated total: ~40 lines.** This is 5–10 lines over the 25–35 budget set in brainstorming. The overshoot is accounted for by D4 (header relocation + SSE error branch) and D5 (X-Accel-Buffering at two sites). Reviewer may reject if actual code lands materially larger than ~45 lines of server.mjs code excluding docs and version files.
+
+## Data flow (streaming request, heartbeat enabled)
+
+1. Client sends `POST /v1/chat/completions` with `stream=true`.
+2. Cache miss → `callClaudeStreaming()` invoked.
+3. `spawn()` claude subprocess succeeds → `ensureHeaders(res)` writes SSE headers including `X-Accel-Buffering: no`.
+4. `const hb = startHeartbeat(res, HEARTBEAT_INTERVAL, sessionId)` arms the watchdog (no-op if interval is 0).
+5. Watchdog ticks after `HEARTBEAT_INTERVAL` ms of idle. On fire: `: keepalive\n\n` out; first-fire logs once; re-arm.
+6. Every real `sendSSE()` write calls `hb.reset()` — cancels and re-arms timer.
+7. Healthy token bursts → heartbeat never fires.
+8. Tool-use pause → timer elapses → heartbeat fires → client stays alive → re-arm → repeat until next chunk arrives.
+9. On proc 'close' (success / `[DONE]`) / proc 'error' / req 'close' / `CLAUDE_TIMEOUT` kill → `hb.stop()`.
+
+## Error handling
+
+- **Client disconnect mid-heartbeat.** `req.on('close')` fires → `hb.stop()`. Any in-flight write becomes a no-op / emits `'error'` on `res`; existing code already tolerates this.
+- **`CLAUDE_TIMEOUT` (600s) fires mid-request.** Existing timeout handler SIGTERM's subprocess → proc 'close' → `hb.stop()`. This PR does **not** fix the separate issue that the current timeout path does not `res.end()` or emit an SSE error frame; that is documented as a separate issue.
+- **`spawn()` throws synchronously.** Heartbeat never started. Existing JSON error response unchanged.
+- **`spawn()` succeeds, subprocess errors before first byte.** Headers have already been written (per D4). Branch emits an SSE error event + `[DONE]` + `res.end()` instead of a JSON error. Documented behavior change.
+
+## Testing plan
+
+OCP has no unit test framework beyond `test-features.mjs`. Verification is manual + cloud-backed.
+
+### Manual local smoke test
+
+1. Set `CLAUDE_HEARTBEAT_INTERVAL=5000` (5s for easy observation) and start OCP.
+2. Issue a streaming completion with a prompt that triggers a tool-use pause (e.g., ask for a large file read or long reasoning):
+   ```
+   curl -N http://localhost:3456/v1/chat/completions \
+     -H "Authorization: Bearer $OCP_KEY" \
+     -d '{"model":"claude-opus-4-7","stream":true,
+           "messages":[{"role":"user","content":"read the attached 200KB text and summarize"}]}'
+   ```
+3. Confirm `: keepalive` comment lines appear in the raw response during the pause, at ~5s cadence.
+4. Confirm `/logs` shows exactly one `heartbeat_active` entry for the request.
+5. With `CLAUDE_HEARTBEAT_INTERVAL=0` (default), confirm no heartbeats and no log line.
+
+### Cloud-backed test run (pre-push, required)
+
+Per project feedback, tests must pass before any push to the public repo. Options, in preference order:
+
+1. **GitHub Actions** — add a temporary smoke workflow (or piggyback on an existing one) that runs `test-features.mjs` against a sandboxed claude mock. Not viable if `test-features.mjs` requires a real claude CLI auth.
+2. **Remote Linux test host via cc-chat handoff** — push feature branch, instruct a cloud machine with claude CLI installed to run the manual steps above, capture output, return verdict via cc-chat.
+3. **Docker/compose locally** — if the maintainer has Docker available, `docker-compose.yml` is present and can be extended.
+
+The implementation subagent and the reviewer subagent MUST include the chosen verification evidence in the PR body (command + output excerpt, sanitized of any identifiers) before the PR is opened for merge review.
+
+### Downstream-parser compatibility
+
+Before merging, verify at least one real downstream client (OCP's own `ocp-connect`, plus — if feasible — the current OpenClaw gateway) does not crash on comment frames. If a target client crashes, either (a) adjust the default to 0 and document the incompatibility, or (b) scope a follow-up PR for `CLAUDE_HEARTBEAT_FORMAT=empty-delta` as an alternative.
+
+## Privacy preflight (for public-repo push)
+
+Before `gh pr create` or any `git push` to `dtzp555-max/ocp`, run the following scan on the full diff (`git diff origin/main...HEAD`):
+
+1. **Use OCP's PR template privacy self-check** — the `.github/PULL_REQUEST_TEMPLATE.md` Privacy self-check section is the canonical list. Fill every checkbox.
+2. **Run `.gitleaks.toml` via gitleaks if available.**
+3. **Manual grep on the diff** for these patterns (sanitize any hits before commit):
+   - Personal names in any language (check commit-author trailers especially — `Co-Authored-By` lines have leaked names before).
+   - Email addresses beyond automated placeholders (`noreply@*`).
+   - Local paths like `/Users/<name>/`, `/home/<name>/`, `C:\Users\<name>\` — replace with `$HOME/` or `~/`.
+   - Machine hostnames — use role-based names or generic descriptors.
+   - IPs, internal URLs, tailnet names.
+4. **Log samples and test output** pasted into spec / README / CHANGELOG / PR body must be sanitized pre-paste, not pre-push. This spec doc itself was drafted under this discipline.
+
+Historical reference: PR #43 / postmortem #44 (2026-04-22) scrubbed a prior leak and established the current apparatus. The user has explicitly flagged this as a scar to avoid re-treading for this PR.
+
+## Scope lock (out of scope)
+
+- `server.mjs:480-489` `CLAUDE_TIMEOUT` dangling-client behavior (no `res.end()` / no SSE error frame on timeout kill) — **will be filed as a separate issue** before this PR opens.
+- Issue #41 (handleSessionFailure deletes on resume only) — separate.
+- Issue #42 (SESSION_TTL and `lastUsed` interaction) — separate.
+- Any new first-byte / idle / adaptive-tier timeout logic — explicitly forbidden per the v3.3 lesson (`server.mjs:8-11`, commit 3843ec8).
+- Non-streaming chat path — no HTTP-level fix possible per [#47](https://github.com/dtzp555-max/ocp/issues/47)'s own conclusion.
+- Named-event format (`event: ping`) or empty-delta JSON chunk variants — possible follow-up PR if field evidence shows comment frames break real clients.
+- Changes to `CLAUDE_TIMEOUT` default — unchanged (stays 600s).
+- Circuit breaker revival — explicitly forbidden.
+
+## ALIGNMENT.md disposition
+
+`cli.js` does not itself emit SSE heartbeat frames — claude CLI speaks newline-delimited JSON to stdout, not SSE. SSE is an OCP-owned translation layer. Per `ALIGNMENT.md` Rule 2 / `AGENTS.md` ("OCP forwards, observes, and multiplexes traffic that cli.js already emits"): heartbeats are a translation-layer response-shaping concern, not a new endpoint and not a behavior mimicry. The PR body will state this explicitly in the `cli.js` citation checkbox and reference this design doc.
+
+## IDR (Iron Rule 11) disposition
+
+Single PR. Scope is one feature (SSE heartbeat) × one layer (streaming response formatting) × one severity (minor opt-in addition). Release-kit companion files (version bump, CHANGELOG, README) are bundled with the code change per the explicit Iron Rule 11 example ("版本 bump 相关的小改动 + README + CHANGELOG 可以同 PR"). The separate filings for the dangling-client bug (`server.mjs:480-489`) and any follow-up heartbeat format variants are IDR-compliant — each lands as its own PR.
+
+## Related
+
+- Issue: [#47](https://github.com/dtzp555-max/ocp/issues/47)
+- Prior timeout scar: commit 3843ec8 (v3.3.0 "simplify timeout to single CLAUDE_TIMEOUT")
+- Prior privacy scar: PR [#43](https://github.com/dtzp555-max/ocp/pull/43) / postmortem [#44](https://github.com/dtzp555-max/ocp/issues/44)
+- Constitution: `ALIGNMENT.md`
+- Project instructions: `AGENTS.md`, `CLAUDE.md`

docs/superpowers/specs/2026-05-07-cache-upgrade-design.md

@@ -0,0 +1,147 @@
+# Design: Response Cache Upgrade (Per-Key Isolation, cache_control Bypass, Chunked Stream Replay, Singleflight)
+
+**Date:** 2026-05-07
+**Status:** Draft (awaiting maintainer approval)
+**Target version:** v3.13.0 (minor — internal correctness/concurrency improvements; no new public env vars or endpoints)
+**Driving ADR:** [ADR 0005 — No Multi-Provider](../../adr/0005-no-multi-provider.md), decision §3 ("Cache improvements are in scope")
+
+---
+
+## Overview
+
+OCP already has a response cache (`keys.mjs:296` `cacheHash` / `keys.mjs:311` `getCachedResponse` / `keys.mjs:324` `setCachedResponse`), wired into the proxy core at `server.mjs:1220` (non-streaming path read), `server.mjs:1227` (cache-hit-on-streaming-request replay), and `server.mjs:683` (streaming write-back). Today it has four functional gaps. This PR pair closes all four, in two minimum-reviewable units, **without changing the public API surface**.
+
+| Gap | Impact today | Fix lands in |
+|---|---|---|
+| All keys share one cache pool | Key A's cache hit can leak Key B's prompt response | PR-A |
+| Anthropic `cache_control` markers not detected | OCP cache may interfere with Anthropic prompt caching that the user explicitly requested | PR-A |
+| Stream cache hit replays whole content in one SSE chunk | Downstream renders all-at-once; some SDKs misbehave on huge single deltas | PR-A |
+| Concurrent identical cache misses all spawn `cli.js` independently | Cache stampede: N requests → N spawns → N billable calls | PR-B |
+
+---
+
+## Constitutional alignment (ALIGNMENT.md)
+
+**`cli.js` does not perform response caching at the proxy layer.** The OCP response cache is a value-add operation that exists only inside OCP, between the wire (clients ↔ OCP) and the spawn (OCP ↔ `cli.js`). It does not introduce, rename, or alter any endpoint, header, request field, or response field that `cli.js` emits or expects. Cache hits return content byte-identical to what `cli.js` returned on the original miss, with the same `chat.completion` / `chat.completion.chunk` shape — **no client-observable wire shape change**.
+
+This PR pair extends the existing cache (introduced in earlier commits) without expanding its surface. No new endpoints. No new headers. No new env vars exposed publicly (we add internal counters readable via the existing `/cache/stats` endpoint, but the response shape only gains numeric fields, not new structural fields).
+
+Per Rule 1 / Rule 5: every commit body in this PR pair will state the absence of `cli.js` reference explicitly and justify scope under Rule 2's value-add carve-out for non-wire-affecting proxy operations.
+
+---
+
+## Key decisions (with rationale)
+
+### D1. Per-key isolation via hash input, not schema column
+
+`cacheHash` gains an optional `keyId` input. Distinct `keyId` values produce distinct hashes for the same prompt, so SQLite-level isolation falls out for free without a schema change.
+
+**Rationale.** Adding a `key_id` column to `response_cache` requires either (a) dropping the existing `hash UNIQUE` index and replacing with a composite `(hash, key_id) UNIQUE`, which SQLite cannot do via plain `ALTER TABLE` and would require a table-rebuild migration, or (b) tolerating duplicate `hash` rows, which contradicts the existing schema comment and breaks `setCachedResponse`'s `ON CONFLICT(hash)` upsert clause.
+
+The hash-input approach is reversible (we can switch to a schema column later if analytics across keys becomes a real need) and zero-risk on the SQL plane. The trade-off — losing the ability to query "which keys have cached this prompt?" — has no current consumer.
+
+**Hash input format.** `cacheHash` prepends a version tag and key tag before the existing inputs:
+
+```
+v2|k:<keyId or "anon">|<model>|...rest as today
+```
+
+The `v2` prefix means existing v1-format rows in the cache table no longer hash-match any new request. They are abandoned, not deleted; the existing TTL-based `clearCache(CACHE_TTL)` cleanup interval at `server.mjs:185` reaps them within one TTL window. **No migration step is needed.** This is acceptable because the cache is by definition ephemeral and best-effort.
+
+**Anonymous fallback.** When the request has no authenticated key (`req._authKeyId === undefined`), `keyId` is `"anon"`. Anonymous-mode users (PROXY_ANONYMOUS_KEY or no auth) share one anonymous pool, which preserves the only legitimate today-multi-user use case (a household running OCP without per-user keys). If this becomes a problem we can add per-IP scoping later, but anonymous-pool sharing is acceptable for v1 because anonymous mode is fundamentally a trust-everyone-on-LAN posture.
+
+### D2. `cache_control` bypass: detect anywhere, skip OCP cache entirely
+
+If any element in `messages` (top-level or nested in `content` arrays) carries a `cache_control` field, OCP sets `req._cacheHash = null` and skips both lookup and write-back.
+
+**Rationale.** Anthropic's [prompt caching](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching) is opt-in by client-side annotation. A user who annotates `cache_control: { type: "ephemeral" }` is explicitly requesting that *Anthropic's* cache serve the call (and is paying the reduced cache-read pricing). Layering OCP's response cache on top in this case is wrong on two counts:
+
+1. The user's intent is "cache at provider, not at proxy." OCP overruling that intent silently is the same drift family as the 2026-04-11 incident — proxy invents behavior the upstream surface doesn't request.
+2. OCP cache hits would make `usage.cache_read_input_tokens` (the client-observable signal that prompt caching worked) appear inconsistent — sometimes present, sometimes absent — depending on whether OCP cached.
+
+Detection is purely structural: walk `messages`, for each `m` check `m.cache_control` (rare top-level form) and if `m.content` is an array, check each part. No semantic interpretation; if the field is present, we bypass.
+
+**Implementation site.** A small helper `hasCacheControl(messages)` exported from `keys.mjs`, called in `handleChatCompletions` immediately before the existing `cacheHash` call. If it returns true, we skip the cache-lookup branch entirely.
+
+### D3. Chunked stream replay (80 chars/chunk, no artificial delay)
+
+Today's cache-hit-on-streaming-request branch (`server.mjs:1227–1237`) sends the entire cached content in a single `delta.content` chunk. This works for spec-compliant SSE clients but visibly degrades the UX (no incremental render) and has tripped at least one buggy SDK in the wild that assumes deltas are small.
+
+The fix splits cached content into ~80-character substrings, each sent as a separate `chat.completion.chunk` SSE event. **No artificial delay between chunks** — they ship as fast as `res.write` accepts. This preserves OCP's "ship as fast as possible" disposition; we are simulating *the chunk shape* of streaming, not the *latency*.
+
+**Why 80 chars?** Compromise: small enough that even a multi-paragraph cached response yields >5 chunks (visible incremental render), large enough that even a 4 KB response only produces 50 chunks (not 4000 single-char events). Tunable later via internal constant; not exposed as env var per scope-creep avoidance.
+
+**Boundary safety.** UTF-8 multibyte characters: we slice by `Array.from(content)` (so each iteration step is a full code point) and group every 80 code points. This avoids producing invalid UTF-8 mid-character.
+
+### D4. Singleflight stampede protection: in-process Map, all-or-nothing failure
+
+`keys.mjs` exports `singleflight(hash, fn)`. An in-memory `Map<hash, Promise>` deduplicates concurrent identical cache-miss flows. The first request executes `fn()`; concurrent requests with the same hash receive the same promise. When the promise settles (resolve or reject), the map entry is deleted.
+
+**Rationale (single-process scope).** OCP runs as a single Node.js process per host. A `Map` is sufficient. Adding Redis or another shared store would be the start of a multi-instance evolution, which is out of scope per ADR 0005 (OCP is a personal power tool, not a horizontally-scaled SaaS).
+
+**All-or-nothing failure semantics.** When the leader's `fn()` rejects, all followers receive the same rejection. The alternative — letting followers retry independently after a leader failure — risks N retries of an already-broken upstream, which is exactly what stampede protection was meant to prevent. Followers can retry at the *next* request, with idle backoff handled by the client. This matches Go's `golang.org/x/sync/singleflight` reference behavior.
+
+**Streaming caveat.** Singleflight wraps the *non-streaming* code path only in PR-B. For streaming, deduplicating concurrent identical streaming requests is materially harder (we'd need to fan out one upstream stream to N downstream connections in real time, with backpressure). It's also a less common case (cache stampedes typically come from non-streaming batch jobs hitting the proxy in parallel). Streaming dedup is **explicitly out of scope** for this PR pair; leave a TODO comment in `callClaudeStreaming` for a future ticket.
+
+**Map size unboundedness.** In normal operation the map is empty most of the time (entries delete on Promise settlement). Pathological case: an upstream call that hangs forever leaks one Map entry per stuck request. The existing `TIMEOUT` guard on `callClaude` (server.mjs spawn timeout) bounds this — the Promise will reject (timeout) within `TIMEOUT` ms, and the entry clears. No additional sweep needed.
+
+---
+
+## PR boundaries
+
+### PR-A — Foundation (D1 + D2 + D3)
+
+**Files touched:**
+- `keys.mjs`: extend `cacheHash` with optional `keyId`/version prefix; add `hasCacheControl(messages)` helper
+- `server.mjs`: pass `req._authKeyId` to `cacheHash`; check `hasCacheControl` and bypass; chunk cache-hit replay at line 1227–1237
+- `test-features.mjs`: add cases for keyId isolation, cache_control bypass, chunked replay shape
+
+**LOC budget:** ~80 production + ~50 test
+**Risk:** Low — all changes are additive or guard-clause; existing cache behavior preserved when `keyId` defaults to "anon" and no `cache_control` present.
+**Backward compat:** v1-format hashes naturally orphan; TTL cleanup reaps within one window; no migration script.
+
+### PR-B — Concurrency (D4)
+
+**Files touched:**
+- `keys.mjs`: add `singleflight(hash, fn)` and `getInflightStats()` exports
+- `server.mjs`: wrap non-streaming cache-miss path through `singleflight`; add inflight count to `/cache/stats` response
+- `test-features.mjs`: add concurrent-request test that asserts only 1 spawn occurs for N=10 simultaneous identical requests
+
+**LOC budget:** ~70 production + ~40 test
+**Risk:** Medium — concurrency code is harder to reason about; mitigation is an explicit test case for the dedup behavior.
+**Streaming explicitly out of scope:** TODO comment placed in `callClaudeStreaming` for follow-up ticket.
+
+---
+
+## Testing strategy
+
+**Unit-ish (in `test-features.mjs`):**
+1. `cacheHash` with two different `keyId` values → different hashes
+2. `cacheHash` v2 prefix present in output (sanity check)
+3. `hasCacheControl` returns true for top-level `cache_control` and for nested in `content[]`
+4. `hasCacheControl` returns false for benign messages
+5. Chunked replay: cached "abcdefgh..." (160 chars) produces 2 deltas
+
+**Integration (manual smoke before merge):**
+1. Set `CLAUDE_CACHE_TTL=60000`; create key A and key B; identical prompt from each → both spawn fresh; second-call from same key → cache hit
+2. Send a message with `cache_control` annotation → OCP logs `cache_skipped: cache_control_present`; no cache write
+3. Streaming cache hit visibly produces multiple SSE deltas (`curl -N | grep "data: "` shows >1 lines)
+
+**Concurrent (PR-B only):**
+1. Spawn 10 simultaneous identical non-streaming requests; assert (via `/cache/stats` inflight peak or via a process spawn counter) only 1 `cli.js` spawn occurred
+
+---
+
+## Out of scope (deliberately deferred)
+
+- **Streaming singleflight** — see D4 streaming caveat. TODO in code.
+- **Semantic cache** (embedding-based near-match) — needs an embedding provider + vector index. Punt to v3.14+ if there's user demand.
+- **Cross-process cache** (Redis backend) — violates ADR 0005's "personal power tool" posture.
+- **Cache versioning by model ID hash** — model upgrades currently invalidate cache organically because model is in the hash; if Anthropic ever silently changes a model's behavior without a model ID bump, that's a separate alignment problem.
+- **Per-key cache TTL override** — single global TTL (existing `CLAUDE_CACHE_TTL`) is fine; per-key TTL is a knob no one has asked for.
+
+---
+
+## Rollback plan
+
+If either PR introduces a regression, the rollback is a clean git revert. The cache layer is opt-in (default `CLAUDE_CACHE_TTL=0` = disabled), so users who never enabled the cache are unaffected by any cache-layer regression. Users who *had* enabled the cache lose only ephemeral state on revert. No persistent on-disk state is reshaped by this PR pair (we explicitly avoid schema migrations per D1 rationale).

keys.mjs

@@ -0,0 +1,416 @@
+// keys.mjs — API key management and usage tracking for OCP LAN mode
+// Uses Node.js built-in SQLite (node:sqlite) — zero external dependencies.
+import { DatabaseSync } from "node:sqlite";
+import { randomBytes, createHash } from "node:crypto";
+import { join } from "node:path";
+import { mkdirSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+
+const OCP_DIR = join(homedir(), ".ocp");
+mkdirSync(OCP_DIR, { recursive: true, mode: 0o700 });
+// Tighten the directory mode in case it already existed with broader permissions.
+try { chmodSync(OCP_DIR, 0o700); } catch { /* ignore EPERM on pre-existing dirs */ }
+const DB_PATH = join(OCP_DIR, "ocp.db");
+
+let db;
+
+export function getDb() {
+  if (!db) {
+    db = new DatabaseSync(DB_PATH);
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA foreign_keys = ON");
+    initSchema();
+    // Tighten mode on the DB file (0600) after creation / first open.
+    try { chmodSync(DB_PATH, 0o600); } catch { /* ignore — same-user access still works */ }
+  }
+  return db;
+}
+
+function initSchema() {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS api_keys (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      key TEXT UNIQUE NOT NULL,
+      name TEXT NOT NULL,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      revoked INTEGER NOT NULL DEFAULT 0
+    );
+
+    CREATE TABLE IF NOT EXISTS usage_log (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      key_id INTEGER,
+      key_name TEXT NOT NULL DEFAULT 'anonymous',
+      model TEXT NOT NULL,
+      prompt_chars INTEGER NOT NULL DEFAULT 0,
+      response_chars INTEGER NOT NULL DEFAULT 0,
+      elapsed_ms INTEGER NOT NULL DEFAULT 0,
+      success INTEGER NOT NULL DEFAULT 1,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      FOREIGN KEY (key_id) REFERENCES api_keys(id)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_usage_created ON usage_log(created_at);
+    CREATE INDEX IF NOT EXISTS idx_usage_key ON usage_log(key_id);
+
+    CREATE TABLE IF NOT EXISTS response_cache (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      hash TEXT UNIQUE NOT NULL,
+      model TEXT NOT NULL,
+      response TEXT NOT NULL,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      last_hit_at TEXT,
+      hits INTEGER NOT NULL DEFAULT 0
+    );
+    CREATE INDEX IF NOT EXISTS idx_cache_hash ON response_cache(hash);
+    CREATE INDEX IF NOT EXISTS idx_cache_created ON response_cache(created_at);
+  `);
+
+  // Idempotent migrations: add quota columns if they don't exist yet.
+  for (const col of [
+    "ALTER TABLE api_keys ADD COLUMN quota_daily INTEGER DEFAULT NULL",
+    "ALTER TABLE api_keys ADD COLUMN quota_weekly INTEGER DEFAULT NULL",
+    "ALTER TABLE api_keys ADD COLUMN quota_monthly INTEGER DEFAULT NULL",
+  ]) {
+    try { db.exec(col); } catch (e) {
+      // SQLite throws "duplicate column name" if already present — safe to ignore.
+      if (!e.message?.includes("duplicate column")) throw e;
+    }
+  }
+}
+
+// ── Key CRUD ──
+
+export function createKey(name) {
+  const key = "ocp_" + randomBytes(24).toString("base64url");
+  const d = getDb();
+  const stmt = d.prepare("INSERT INTO api_keys (key, name) VALUES (?, ?)");
+  const result = stmt.run(key, name);
+  return { id: result.lastInsertRowid, key, name };
+}
+
+export function listKeys() {
+  const d = getDb();
+  return d.prepare(
+    "SELECT id, key, name, created_at, revoked, quota_daily, quota_weekly, quota_monthly FROM api_keys ORDER BY created_at DESC"
+  ).all().map(({ key, ...rest }) => ({
+    ...rest,
+    keyPreview: key.slice(0, 8) + "..." + key.slice(-4),
+  }));
+}
+
+export function revokeKey(idOrName) {
+  const d = getDb();
+  const stmt = d.prepare(
+    "UPDATE api_keys SET revoked = 1 WHERE (id = ? OR name = ?) AND revoked = 0"
+  );
+  return stmt.run(idOrName, idOrName).changes > 0;
+}
+
+export function validateKey(key) {
+  const d = getDb();
+  const row = d.prepare(
+    "SELECT id, name FROM api_keys WHERE key = ? AND revoked = 0"
+  ).get(key);
+  return row || null;
+}
+
+// ── Usage recording ──
+
+export function recordUsage({ keyId, keyName, model, promptChars, responseChars, elapsedMs, success }) {
+  const d = getDb();
+  d.prepare(`
+    INSERT INTO usage_log (key_id, key_name, model, prompt_chars, response_chars, elapsed_ms, success)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).run(keyId ?? null, keyName || "anonymous", model, promptChars, responseChars, elapsedMs, success ? 1 : 0);
+}
+
+// ── Usage queries ──
+
+export function getUsageByKey({ since, until } = {}) {
+  const d = getDb();
+  let where = "WHERE 1=1";
+  const params = [];
+  if (since) { where += " AND created_at >= ?"; params.push(since); }
+  if (until) { where += " AND created_at <= ?"; params.push(until); }
+
+  return d.prepare(`
+    SELECT
+      key_name,
+      COUNT(*) as requests,
+      SUM(CASE WHEN success = 1 THEN 1 ELSE 0 END) as successes,
+      SUM(CASE WHEN success = 0 THEN 1 ELSE 0 END) as errors,
+      SUM(prompt_chars) as total_prompt_chars,
+      SUM(response_chars) as total_response_chars,
+      SUM(elapsed_ms) as total_elapsed_ms,
+      AVG(elapsed_ms) as avg_elapsed_ms,
+      MIN(created_at) as first_request,
+      MAX(created_at) as last_request
+    FROM usage_log
+    ${where}
+    GROUP BY key_name
+    ORDER BY requests DESC
+  `).all(...params);
+}
+
+export function getUsageTimeline({ keyName, hours = 24 } = {}) {
+  const d = getDb();
+  const since = new Date(Date.now() - hours * 3600000).toISOString();
+  let where = "WHERE created_at >= ?";
+  const params = [since];
+  if (keyName) { where += " AND key_name = ?"; params.push(keyName); }
+
+  return d.prepare(`
+    SELECT
+      strftime('%Y-%m-%dT%H:00:00', created_at) as hour,
+      COUNT(*) as requests,
+      SUM(prompt_chars) as prompt_chars,
+      SUM(response_chars) as response_chars,
+      AVG(elapsed_ms) as avg_elapsed_ms
+    FROM usage_log
+    ${where}
+    GROUP BY hour
+    ORDER BY hour
+  `).all(...params);
+}
+
+export function getRecentUsage(limit = 50) {
+  const d = getDb();
+  return d.prepare(`
+    SELECT key_name, model, prompt_chars, response_chars, elapsed_ms, success, created_at
+    FROM usage_log
+    ORDER BY created_at DESC
+    LIMIT ?
+  `).all(limit);
+}
+
+// ── SQLite datetime helper ──
+// SQLite datetime('now') stores as 'YYYY-MM-DD HH:MM:SS' (no T, no Z).
+// JavaScript .toISOString() produces 'YYYY-MM-DDTHH:MM:SS.sssZ'.
+// String comparison between the two breaks for same-day ranges (T > space).
+// This helper formats Date to match SQLite's format for correct comparisons.
+function sqliteDatetime(date) {
+  return date.toISOString().replace("T", " ").replace(/\.\d{3}Z$/, "");
+}
+
+// ── Quota management ──
+
+// Returns { period, limit, used, resetsIn } if a quota is exceeded, null otherwise.
+// Anonymous/admin callers (keyId === null) are never subject to quotas.
+export function checkQuota(keyId, _keyName) {
+  if (keyId === null || keyId === undefined) return null;
+
+  const d = getDb();
+  const keyRow = d.prepare(
+    "SELECT quota_daily, quota_weekly, quota_monthly FROM api_keys WHERE id = ? AND revoked = 0"
+  ).get(keyId);
+  if (!keyRow) return null;
+
+  const now = new Date();
+
+  // UTC period boundaries (SQLite-compatible format)
+  const startOfToday = sqliteDatetime(new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate())));
+  const sevenDaysAgo = sqliteDatetime(new Date(Date.now() - 7 * 86400000));
+  const thirtyDaysAgo = sqliteDatetime(new Date(Date.now() - 30 * 86400000));
+
+  // Next reset times for human display
+  const tomorrowUTC = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1));
+  function msToHuman(ms) {
+    if (ms <= 0) return "now";
+    const h = Math.floor(ms / 3600000);
+    const m = Math.floor((ms % 3600000) / 60000);
+    if (h >= 24) { const d = Math.floor(h / 24); return `${d}d ${h % 24}h`; }
+    return h > 0 ? `${h}h ${m}m` : `${m}m`;
+  }
+
+  // Single query for all periods (widest window = monthly)
+  const row = d.prepare(`
+    SELECT
+      SUM(CASE WHEN created_at >= ? THEN 1 ELSE 0 END) as daily_cnt,
+      SUM(CASE WHEN created_at >= ? THEN 1 ELSE 0 END) as weekly_cnt,
+      COUNT(*) as monthly_cnt
+    FROM usage_log
+    WHERE key_id = ? AND success = 1 AND created_at >= ?
+  `).get(startOfToday, sevenDaysAgo, keyId, thirtyDaysAgo);
+
+  const checks = [
+    { period: "daily",   limit: keyRow.quota_daily,   used: row?.daily_cnt ?? 0,   resetsIn: msToHuman(tomorrowUTC - now) },
+    { period: "weekly",  limit: keyRow.quota_weekly,  used: row?.weekly_cnt ?? 0,  resetsIn: "rolling 7-day window" },
+    { period: "monthly", limit: keyRow.quota_monthly, used: row?.monthly_cnt ?? 0, resetsIn: "rolling 30-day window" },
+  ];
+
+  for (const { period, limit, used, resetsIn } of checks) {
+    if (limit === null || limit === undefined) continue;
+    if (used >= limit) {
+      return { period, limit, used, resetsIn };
+    }
+  }
+
+  return null;
+}
+
+// Set quota for a key. Only updates fields explicitly present in the input object.
+// Pass null to clear a specific limit. Omit a field to leave it unchanged.
+export function updateKeyQuota(idOrName, updates = {}) {
+  const d = getDb();
+  const setClauses = [];
+  const params = [];
+  if ("daily" in updates)  { setClauses.push("quota_daily = ?");  params.push(updates.daily ?? null); }
+  if ("weekly" in updates) { setClauses.push("quota_weekly = ?"); params.push(updates.weekly ?? null); }
+  if ("monthly" in updates){ setClauses.push("quota_monthly = ?");params.push(updates.monthly ?? null); }
+  if (setClauses.length === 0) return false;
+  params.push(idOrName, idOrName);
+  const result = d.prepare(
+    `UPDATE api_keys SET ${setClauses.join(", ")} WHERE id = ? OR name = ?`
+  ).run(...params);
+  return result.changes > 0;
+}
+
+// Returns { daily: { limit, used }, weekly: { limit, used }, monthly: { limit, used } }
+export function getKeyQuota(keyId) {
+  const d = getDb();
+  const keyRow = d.prepare(
+    "SELECT quota_daily, quota_weekly, quota_monthly FROM api_keys WHERE id = ?"
+  ).get(keyId);
+  if (!keyRow) return null;
+
+  const now = new Date();
+  const startOfToday  = sqliteDatetime(new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate())));
+  const sevenDaysAgo  = sqliteDatetime(new Date(Date.now() - 7 * 86400000));
+  const thirtyDaysAgo = sqliteDatetime(new Date(Date.now() - 30 * 86400000));
+
+  const row = d.prepare(`
+    SELECT
+      SUM(CASE WHEN created_at >= ? THEN 1 ELSE 0 END) as daily_cnt,
+      SUM(CASE WHEN created_at >= ? THEN 1 ELSE 0 END) as weekly_cnt,
+      COUNT(*) as monthly_cnt
+    FROM usage_log
+    WHERE key_id = ? AND success = 1 AND created_at >= ?
+  `).get(startOfToday, sevenDaysAgo, keyId, thirtyDaysAgo);
+
+  return {
+    daily:   { limit: keyRow.quota_daily   ?? null, used: row?.daily_cnt ?? 0 },
+    weekly:  { limit: keyRow.quota_weekly  ?? null, used: row?.weekly_cnt ?? 0 },
+    monthly: { limit: keyRow.quota_monthly ?? null, used: row?.monthly_cnt ?? 0 },
+  };
+}
+
+// ── Response cache ──
+
+// Generate a cache key from model + messages + request params that affect output.
+// opts.keyId isolates per-API-key cache pools (v2 hash format).
+// When keyId is absent/null/empty, falls back to "anon" (shared anonymous pool).
+export function cacheHash(model, messages, opts = {}) {
+  const keyId = opts.keyId || "anon";
+  const h = createHash("sha256");
+  h.update(`v2|k:${keyId}|`);
+  h.update(model);
+  if (opts.temperature != null) h.update(`t:${opts.temperature}`);
+  if (opts.max_tokens != null) h.update(`mt:${opts.max_tokens}`);
+  if (opts.top_p != null) h.update(`tp:${opts.top_p}`);
+  for (const m of messages) {
+    h.update(m.role || "");
+    h.update(typeof m.content === "string" ? m.content : JSON.stringify(m.content));
+  }
+  return h.digest("hex");
+}
+
+// Check whether any message (or content part) carries an Anthropic cache_control field.
+// If true, OCP should skip its own cache to avoid interfering with prompt-caching intent.
+export function hasCacheControl(messages) {
+  for (const m of messages || []) {
+    if (m && typeof m === "object") {
+      if (m.cache_control) return true;
+      if (Array.isArray(m.content)) {
+        for (const part of m.content) {
+          if (part && typeof part === "object" && part.cache_control) return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+
+// Look up a cached response. Returns { response, hits } or null.
+// Also updates last_hit_at and increments hits counter on hit.
+export function getCachedResponse(hash, ttlMs) {
+  const d = getDb();
+  const cutoff = sqliteDatetime(new Date(Date.now() - ttlMs));
+  const row = d.prepare(
+    "SELECT id, response, hits FROM response_cache WHERE hash = ? AND created_at >= ?"
+  ).get(hash, cutoff);
+  if (!row) return null;
+  // Update hit stats
+  d.prepare("UPDATE response_cache SET hits = hits + 1, last_hit_at = datetime('now') WHERE id = ?").run(row.id);
+  return { response: row.response, hits: row.hits + 1 };
+}
+
+// Store a response in the cache
+export function setCachedResponse(hash, model, response) {
+  const d = getDb();
+  // Upsert: if hash already exists (race condition), just update
+  d.prepare(`
+    INSERT INTO response_cache (hash, model, response) VALUES (?, ?, ?)
+    ON CONFLICT(hash) DO UPDATE SET response = excluded.response, created_at = datetime('now'), hits = 0
+  `).run(hash, model, response);
+}
+
+// Clear all cached responses, or expired ones only
+export function clearCache(ttlMs = null) {
+  const d = getDb();
+  if (ttlMs === null) {
+    const result = d.prepare("DELETE FROM response_cache").run();
+    return result.changes;
+  }
+  const cutoff = sqliteDatetime(new Date(Date.now() - ttlMs));
+  const result = d.prepare("DELETE FROM response_cache WHERE created_at < ?").run(cutoff);
+  return result.changes;
+}
+
+// Get cache statistics
+export function getCacheStats() {
+  const d = getDb();
+  const total = d.prepare("SELECT COUNT(*) as cnt FROM response_cache").get()?.cnt ?? 0;
+  const totalHits = d.prepare("SELECT SUM(hits) as total FROM response_cache").get()?.total ?? 0;
+  const sizeBytes = d.prepare("SELECT SUM(LENGTH(response)) as size FROM response_cache").get()?.size ?? 0;
+  return { entries: total, totalHits, sizeBytes };
+}
+
+// ── Singleflight stampede protection ──
+
+// In-memory singleflight Map: hash → { promise, requesters }
+// Deduplicates concurrent identical cache-miss flows so only one upstream call runs.
+// Per ADR 0005 / spec D4: in-process scope only (single Node process per host).
+const inflightMap = new Map();
+
+export function singleflight(hash, fn) {
+  const existing = inflightMap.get(hash);
+  if (existing) {
+    existing.requesters++;
+    return existing.promise;
+  }
+  // Wrap fn() in Promise.resolve().then() so synchronous throws don't escape.
+  const promise = Promise.resolve().then(fn).finally(() => {
+    inflightMap.delete(hash);
+  });
+  inflightMap.set(hash, { promise, requesters: 1 });
+  return promise;
+}
+
+export function getInflightStats() {
+  let totalRequesters = 0;
+  for (const entry of inflightMap.values()) totalRequesters += entry.requesters;
+  return {
+    inflight: inflightMap.size,
+    requesters: totalRequesters,
+  };
+}
+
+// Find a key by id or name (returns { id, name } or null)
+export function findKey(idOrName) {
+  const d = getDb();
+  return d.prepare("SELECT id, name FROM api_keys WHERE id = ? OR name = ?").get(idOrName, idOrName) || null;
+}
+
+export function closeDb() {
+  if (db) { db.close(); db = null; }
+}

memory/constitution.md

@@ -0,0 +1,50 @@
+# OCP Constitution
+<!-- Created by spec-kit integration (github/spec-kit v0.7.3) -->
+<!--
+NOTE TO CLAUDE SESSIONS: This file is the spec-kit constitution for the OCP repo.
+It coexists with — and is subordinate to — the project-specific constraints in
+~/ocp/AGENTS.md. Always read AGENTS.md first for memory policies, protected files,
+and development discipline rules. This constitution covers spec-driven development
+principles for new features.
+-->
+
+## Core Principles
+
+### I. Spec-First Development
+All non-trivial features begin with a specification in `specs/` before any code is written.
+Use `/speckit-specify` to create the spec, `/speckit-plan` for the implementation plan,
+`/speckit-tasks` to generate the task list, then `/speckit-implement` to execute.
+
+### II. Server Integrity (NON-NEGOTIABLE)
+`server.mjs`, `models.json`, `package.json`, and `keys.mjs` are protected files.
+No spec-driven workflow may modify them without explicit approval from the project
+maintainer. If a spec calls for changes to these files, halt and escalate.
+
+### III. Test-First
+Implementation tasks include tests before code. The `/speckit-implement` command
+must follow TDD for any logic touching the proxy or model-routing paths.
+
+### IV. Additive by Default
+Features should be additive — new endpoints, new model entries, new config flags —
+not modifications to existing contracts unless the spec explicitly justifies the
+breaking change and the plan documents a migration path.
+
+### V. Cross-Device Compatibility
+OCP runs on multiple machines. Specs and plans committed to `specs/` serve as the
+cross-device handoff artifact. Keep `specs/NNN/tasks.md` updated as the canonical
+work-state file.
+
+## Constraints
+
+- Follow CC 开发铁律 v1.3 (Iron Rules) as loaded via `/cc-rules` in CLAUDE.md.
+- One PR per reviewable unit (Iron Rule 11 IDR).
+- Independent review required before merge (Iron Rule 10).
+- Pre-brainstorm prior-art search required (Iron Rule 12).
+
+## Governance
+
+This constitution is subordinate to `AGENTS.md` for project-specific memory policy
+and to CC 开发铁律 for development discipline. Amendments require a PR reviewed by
+the project maintainer.
+
+**Version**: 1.0.0 | **Ratified**: 2026-04-21 | **Last Amended**: 2026-04-21

models.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "./models.schema.json",
+  "version": 1,
+  "models": [
+    {
+      "id": "claude-opus-4-7",
+      "displayName": "Claude Opus 4.7",
+      "openclawName": "Claude Opus 4.7 (via CLI)",
+      "reasoning": true,
+      "contextWindow": 200000,
+      "maxTokens": 16384
+    },
+    {
+      "id": "claude-opus-4-6",
+      "displayName": "Claude Opus 4.6",
+      "openclawName": "Claude Opus 4.6 (via CLI)",
+      "reasoning": true,
+      "contextWindow": 200000,
+      "maxTokens": 16384
+    },
+    {
+      "id": "claude-sonnet-4-6",
+      "displayName": "Claude Sonnet 4.6",
+      "openclawName": "Claude Sonnet 4.6 (via CLI)",
+      "reasoning": true,
+      "contextWindow": 200000,
+      "maxTokens": 16384
+    },
+    {
+      "id": "claude-haiku-4-5-20251001",
+      "displayName": "Claude Haiku 4.5",
+      "openclawName": "Claude Haiku 4.5 (via CLI)",
+      "reasoning": false,
+      "contextWindow": 200000,
+      "maxTokens": 8192
+    }
+  ],
+  "aliases": {
+    "opus": "claude-opus-4-7",
+    "sonnet": "claude-sonnet-4-6",
+    "haiku": "claude-haiku-4-5-20251001"
+  },
+  "legacyAliases": {
+    "claude-opus-4": "claude-opus-4-7",
+    "claude-haiku-4": "claude-haiku-4-5-20251001",
+    "claude-haiku-4-5": "claude-haiku-4-5-20251001"
+  }
+}

ocp

@@ -0,0 +1,908 @@
+#!/usr/bin/env bash
+# ocp — OpenClaw Proxy CLI
+# Usage: ocp <command> [args]
+#
+# Talks to the local claude-proxy at http://127.0.0.1:3456
+
+set -euo pipefail
+
+PROXY="http://127.0.0.1:3456"
+
+# Auth args for multi-key mode: reads from OCP_ADMIN_KEY env or ~/.ocp/admin-key file
+# Using a bash array preserves word boundaries — no eval needed.
+_AUTH_ARGS=()
+if [[ -n "${OCP_ADMIN_KEY:-}" ]]; then
+  _AUTH_ARGS=(-H "Authorization: Bearer $OCP_ADMIN_KEY")
+elif [[ -f "$HOME/.ocp/admin-key" ]]; then
+  _AUTH_ARGS=(-H "Authorization: Bearer $(cat "$HOME/.ocp/admin-key")")
+fi
+
+# Wrapper: curl with optional auth
+_curl() {
+  curl "${_AUTH_ARGS[@]}" "$@"
+}
+
+_json() { python3 -m json.tool 2>/dev/null || cat; }
+
+_bar() {
+  local pct=$1 width=20
+  local filled=$(( pct * width / 100 ))
+  local empty=$(( width - filled ))
+  printf '['
+  printf '█%.0s' $(seq 1 $filled 2>/dev/null) || true
+  printf '░%.0s' $(seq 1 $empty 2>/dev/null) || true
+  printf '] %d%%' "$pct"
+}
+
+# ── usage ────────────────────────────────────────────────────────────────
+cmd_usage_help() {
+  cat <<'EOF'
+ocp usage — Show Claude plan usage limits
+
+Displays current session utilization, weekly limits, extra usage status,
+and proxy request statistics. Data is fetched from the Anthropic API
+via a minimal probe call (cached for 5 minutes).
+
+Usage: ocp usage [--by-key]
+
+Options:
+  --by-key    Show per-key usage statistics
+EOF
+}
+
+cmd_usage() {
+  if [[ "${1:-}" == "--by-key" ]]; then
+    local data
+    data=$(_curl -sf --max-time 15 "$PROXY/api/usage" 2>&1) || { echo "Error: proxy unreachable or usage API not available"; exit 1; }
+    echo "$data" | python3 -c "
+import sys, json
+d = json.loads(sys.stdin.read())
+by_key = d.get('byKey', [])
+if not by_key:
+    print('No usage data yet.')
+else:
+    print('Usage by Key')
+    print('─────────────────────────────────────────────────────────────────')
+    hdr = f'  {\"Key\":<20} {\"Reqs\":>5} {\"OK\":>4} {\"Err\":>4} {\"Avg Time\":>9} {\"Last Request\":<20}'
+    print(hdr)
+    print('  ' + '─' * (len(hdr) - 2))
+    for k in by_key:
+        avg_t = f'{k[\"avg_elapsed_ms\"]/1000:.1f}s' if k['avg_elapsed_ms'] else '-'
+        print(f'  {k[\"key_name\"]:<20} {k[\"requests\"]:>5} {k[\"successes\"]:>4} {k[\"errors\"]:>4} {avg_t:>9} {k[\"last_request\"]:<20}')
+"
+    return
+  fi
+
+  local data
+  data=$(curl -sf --max-time 15 "$PROXY/usage" 2>&1) || { echo "Error: proxy unreachable"; exit 1; }
+
+  echo "$data" | python3 -c "
+import sys, json
+
+d = json.loads(sys.stdin.read())
+p = d['plan']
+s = p['currentSession']
+w = p['weeklyLimits']['allModels']
+e = p['extraUsage']
+px = d['proxy']
+models = d.get('models', {})
+
+print('Plan Usage Limits')
+print('─────────────────────────────────────')
+print(f'  Current session     {s[\"percent\"]:>4} used')
+print(f'                      Resets in {s[\"resetsIn\"]}  ({s[\"resetsAtHuman\"]})')
+print()
+print(f'  Weekly (all models) {w[\"percent\"]:>4} used')
+print(f'                      Resets in {w[\"resetsIn\"]}  ({w[\"resetsAtHuman\"]})')
+print()
+status_icon = 'on' if e['status'] == 'allowed' else 'off'
+print(f'  Extra usage         {status_icon}')
+print()
+
+if models:
+    print('Model Stats (since proxy start)')
+    print('─────────────────────────────────────────────────────────────────────')
+    hdr = f'  {\"Model\":<25} {\"Reqs\":>5} {\"OK\":>4} {\"Err\":>4} {\"Avg Time\":>9} {\"Max Time\":>9} {\"Avg Prompt\":>11} {\"Max Prompt\":>11}'
+    print(hdr)
+    print('  ' + '─' * (len(hdr) - 2))
+    total_reqs = 0
+    for model in sorted(models):
+        m = models[model]
+        total_reqs += m['requests']
+        avg_t = f'{m[\"avgElapsed\"]/1000:.0f}s' if m['avgElapsed'] else '-'
+        max_t = f'{m[\"maxElapsed\"]/1000:.0f}s' if m['maxElapsed'] else '-'
+        avg_p = f'{m[\"avgPromptChars\"]/1000:.0f}K' if m['avgPromptChars'] else '-'
+        max_p = f'{m[\"maxPromptChars\"]/1000:.0f}K' if m['maxPromptChars'] else '-'
+        print(f'  {model:<25} {m[\"requests\"]:>5} {m[\"successes\"]:>4} {m[\"errors\"]:>4} {avg_t:>9} {max_t:>9} {avg_p:>11} {max_p:>11}')
+    print(f'  {\"Total\":<25} {total_reqs:>5}')
+else:
+    print('  No model requests yet.')
+
+print()
+print(f'Proxy: up {px[\"uptime\"]} | {px[\"totalRequests\"]} reqs | {px[\"activeRequests\"]} active | {px[\"errors\"]} err | {px[\"timeouts\"]} timeout')
+"
+}
+
+# ── status ───────────────────────────────────────────────────────────────
+cmd_status_help() {
+  cat <<'EOF'
+ocp status — Quick combined overview (usage + health)
+
+Usage: ocp status
+EOF
+}
+
+cmd_status() {
+  curl -sf --max-time 15 "$PROXY/status" | _json
+}
+
+# ── health ───────────────────────────────────────────────────────────────
+cmd_health_help() {
+  cat <<'EOF'
+ocp health — Proxy health and diagnostics
+
+Shows proxy status, version, uptime, auth, config, sessions, and recent errors.
+
+Usage: ocp health
+EOF
+}
+
+cmd_health() {
+  curl -sf --max-time 10 "$PROXY/health" | _json
+}
+
+# ── logs ─────────────────────────────────────────────────────────────────
+cmd_logs_help() {
+  cat <<'EOF'
+ocp logs — Show recent proxy log entries
+
+Usage: ocp logs [N] [LEVEL]
+
+Arguments:
+  N       Number of entries to show (default: 20, max: 200)
+  LEVEL   Filter level: error, warn, info, all (default: error)
+
+Examples:
+  ocp logs              Last 20 errors
+  ocp logs 50 all       Last 50 entries of any level
+  ocp logs 10 warn      Last 10 warnings
+EOF
+}
+
+cmd_logs() {
+  local n=${1:-20}
+  local level=${2:-error}
+  curl -sf --max-time 10 "$PROXY/logs?n=$n&level=$level" | python3 -c "
+import sys, json
+d = json.loads(sys.stdin.read())
+entries = d.get('entries', [])
+if not entries:
+    print(f'No {d.get(\"level\",\"\")} log entries.')
+else:
+    for e in entries:
+        if 'raw' in e:
+            print(e['raw'][:200])
+        else:
+            ts = e.get('ts','')[:19]
+            ev = e.get('event','?')
+            lvl = e.get('level','')
+            model = e.get('model','')
+            extra = ' '.join(f'{k}={v}' for k,v in e.items() if k not in ('ts','event','level','model'))
+            parts = [ts, lvl.upper(), ev]
+            if model: parts.append(model)
+            if extra: parts.append(extra)
+            print(' | '.join(parts))
+"
+}
+
+# ── models ───────────────────────────────────────────────────────────────
+cmd_models_help() {
+  cat <<'EOF'
+ocp models — List available Claude models
+
+Usage: ocp models
+EOF
+}
+
+cmd_models() {
+  curl -sf --max-time 5 "$PROXY/v1/models" | python3 -c "
+import sys, json
+d = json.loads(sys.stdin.read())
+for m in d.get('data', []):
+    print(f\"  {m['id']}\")
+"
+}
+
+# ── sessions ─────────────────────────────────────────────────────────────
+cmd_sessions_help() {
+  cat <<'EOF'
+ocp sessions — List active CLI sessions
+
+Usage: ocp sessions
+EOF
+}
+
+cmd_sessions() {
+  curl -sf --max-time 5 "$PROXY/sessions" | python3 -c "
+import sys, json
+d = json.loads(sys.stdin.read())
+sessions = d.get('sessions', [])
+if not sessions:
+    print('No active sessions.')
+else:
+    for s in sessions:
+        print(f\"  {s['id'][:16]}...  model={s['model']}  msgs={s['messages']}  last={s['lastUsed']}\")
+"
+}
+
+# ── clear ────────────────────────────────────────────────────────────────
+cmd_clear_help() {
+  cat <<'EOF'
+ocp clear — Clear all active CLI sessions
+
+Usage: ocp clear
+EOF
+}
+
+cmd_clear() {
+  local result
+  result=$(curl -sf --max-time 5 -X DELETE "$PROXY/sessions")
+  local count
+  count=$(echo "$result" | python3 -c "import sys,json; print(json.loads(sys.stdin.read())['cleared'])")
+  echo "Cleared $count sessions."
+}
+
+# ── keys ────────────────────────────────────────────────────────────────
+cmd_keys_help() {
+  cat <<'EOF'
+ocp keys — Manage API keys (multi-key auth mode)
+
+Usage:
+  ocp keys                     List all keys
+  ocp keys add <name>          Create a new key
+  ocp keys revoke <name|id>    Revoke a key
+
+Examples:
+  ocp keys add wife-laptop
+  ocp keys add son-ipad
+  ocp keys revoke wife-laptop
+EOF
+}
+
+cmd_keys() {
+  case "${1:-}" in
+    add)
+      if [[ -z "${2:-}" ]]; then echo "Usage: ocp keys add <name>"; return 1; fi
+      local result
+      result=$(_curl -sf --max-time 5 -X POST "$PROXY/api/keys" \
+        -H "Content-Type: application/json" \
+        -d "{\"name\": \"$2\"}" 2>&1) || { echo "Error: proxy unreachable or unauthorized"; exit 1; }
+      echo "$result" | python3 -c "
+import sys, json
+d = json.loads(sys.stdin.read())
+if 'key' in d:
+    print(f'✓ Key created for \"{d[\"name\"]}\"')
+    print(f'')
+    print(f'  API Key: {d[\"key\"]}')
+    print(f'')
+    print(f'  Copy this key now — you won\\'t see it again.')
+    print(f'  Configure in IDE: OPENAI_API_KEY={d[\"key\"]}')
+else:
+    print(f'✗ {d.get(\"error\", \"Unknown error\")}')
+"
+      ;;
+    revoke)
+      if [[ -z "${2:-}" ]]; then echo "Usage: ocp keys revoke <name|id>"; return 1; fi
+      _curl -sf --max-time 5 -X DELETE "$PROXY/api/keys/$2" | python3 -c "
+import sys, json
+d = json.loads(sys.stdin.read())
+if d.get('revoked'):
+    print(f'✓ Key \"{d[\"idOrName\"]}\" revoked.')
+else:
+    print(f'✗ Key not found or already revoked.')
+"
+      ;;
+    --help|-h)
+      cmd_keys_help
+      ;;
+    "")
+      _curl -sf --max-time 5 "$PROXY/api/keys" | python3 -c "
+import sys, json
+d = json.loads(sys.stdin.read())
+keys = d.get('keys', [])
+if not keys:
+    print('No API keys configured.')
+    print('Create one: ocp keys add <name>')
+else:
+    print('API Keys')
+    print('─────────────────────────────────────────────────')
+    for k in keys:
+        status = '✗ revoked' if k['revoked'] else '✓ active'
+        print(f'  {k[\"name\"]:<20} {k[\"keyPreview\"]:<20} {status}  {k[\"created_at\"]}')
+" 2>/dev/null || { echo "Error: proxy unreachable or key management not available"; exit 1; }
+      ;;
+    *)
+      echo "Unknown subcommand: $1"; cmd_keys_help; return 1 ;;
+  esac
+}
+
+# ── connect ─────────────────────────────────────────────────────────────
+cmd_connect_help() {
+  cat <<'EOF'
+ocp connect — Connect this machine to a remote OCP as a LAN client
+
+Configures OPENAI_BASE_URL (and optionally OPENAI_API_KEY) in your shell
+rc file so tools like Claude Code point to a remote OCP instance.
+
+Usage:
+  ocp connect <host-ip> [--port PORT] [--key API_KEY]
+
+Arguments:
+  host-ip          IP address of the machine running OCP
+  --port PORT      Port OCP listens on (default: 3456)
+  --key API_KEY    API key to use (prompted if remote requires auth)
+
+Examples:
+  ocp connect 192.168.1.10
+  ocp connect 192.168.1.10 --port 8080
+  ocp connect 192.168.1.10 --key sk-abc123
+EOF
+}
+
+cmd_connect() {
+  local host="" port=3456 key=""
+
+  # Parse args
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --port)  port="${2:?'--port requires a value'}"; shift 2 ;;
+      --key)   key="${2:?'--key requires a value'}"; shift 2 ;;
+      --help|-h) cmd_connect_help; return 0 ;;
+      -*)      echo "Unknown option: $1"; cmd_connect_help; return 1 ;;
+      *)       host="$1"; shift ;;
+    esac
+  done
+
+  if [[ -z "$host" ]]; then
+    echo "Error: host IP is required."
+    echo ""
+    cmd_connect_help
+    return 1
+  fi
+
+  if ! [[ "$host" =~ ^[a-zA-Z0-9._-]+$ ]]; then
+    echo "Error: invalid host '$host'"
+    return 1
+  fi
+
+  local base_url="http://$host:$port"
+
+  echo "OCP Connect"
+  echo "─────────────────────────────────────"
+  echo "  Remote: $base_url"
+  echo ""
+
+  # Step 1: Test connectivity via /health
+  echo "  Checking connectivity..."
+  local health_json
+  health_json=$(curl -sf --max-time 10 "$base_url/health" 2>/dev/null) || {
+    echo "  ✗ Cannot reach $base_url/health"
+    echo "    Make sure OCP is running on $host and bound to 0.0.0.0 (LAN mode)."
+    return 1
+  }
+  echo "  ✓ Connected"
+  echo ""
+
+  # Step 2: Show remote info
+  local remote_version auth_mode
+  remote_version=$(echo "$health_json" | python3 -c "import sys,json; d=json.loads(sys.stdin.read()); print(d.get('version','?'))" 2>/dev/null || echo "?")
+  auth_mode=$(echo "$health_json" | python3 -c "import sys,json; d=json.loads(sys.stdin.read()); print(d.get('authMode','none'))" 2>/dev/null || echo "none")
+
+  echo "  Remote OCP v$remote_version  (auth: $auth_mode)"
+  echo ""
+
+  # Step 3: Determine if key is needed
+  local needs_key=0
+  if [[ "$auth_mode" != "none" ]]; then
+    needs_key=1
+  fi
+
+  if [[ $needs_key -eq 1 && -z "$key" ]]; then
+    echo "  Remote requires authentication."
+    echo "  Ask the admin to run:  ocp keys add <name>"
+    printf "  Enter API key (or press Enter to skip): "
+    read -rs key </dev/tty
+    echo
+    if [[ -z "$key" ]]; then
+      echo ""
+      echo "  ✗ No key provided — cannot connect to an auth-required remote without a key."
+      return 1
+    fi
+  fi
+
+  # Step 4: Test API access via /v1/models
+  echo "  Testing API access..."
+  local models_out models_ok=0
+  if [[ -n "$key" ]]; then
+    models_out=$(curl -sf --max-time 10 \
+      -H "Authorization: Bearer $key" \
+      "$base_url/v1/models" 2>/dev/null) && models_ok=1
+  else
+    models_out=$(curl -sf --max-time 10 "$base_url/v1/models" 2>/dev/null) && models_ok=1
+  fi
+
+  if [[ $models_ok -eq 0 ]]; then
+    echo "  ✗ API access failed — key may be invalid or revoked."
+    return 1
+  fi
+  local model_count
+  model_count=$(echo "$models_out" | python3 -c "import sys,json; print(len(json.loads(sys.stdin.read()).get('data',[])))" 2>/dev/null || echo "?")
+  echo "  ✓ API accessible ($model_count models available)"
+  echo ""
+
+  # Step 5: Detect shell rc file
+  local rc_file
+  if [[ "${SHELL:-}" == */zsh ]]; then
+    rc_file="$HOME/.zshrc"
+  else
+    rc_file="$HOME/.bashrc"
+  fi
+
+  # Step 6: Remove any previously written OCP LAN lines
+  if [[ -f "$rc_file" ]]; then
+    local tmp_rc
+    tmp_rc=$(mktemp)
+    if python3 - "$rc_file" "$tmp_rc" <<'PYEOF'
+import sys
+src, dst = sys.argv[1], sys.argv[2]
+lines = open(src).readlines()
+out = []
+skip = False
+for line in lines:
+    s = line.rstrip('\n')
+    if s == '# OCP LAN (added by ocp connect)':
+        skip = True
+        continue
+    if skip and (s == '' or s.startswith('export OPENAI_BASE_URL=') or s.startswith('export OPENAI_API_KEY=')):
+        continue
+    skip = False
+    out.append(line)
+open(dst, 'w').writelines(out)
+PYEOF
+    then
+      cp "$tmp_rc" "$rc_file"
+    fi
+    rm -f "$tmp_rc"
+  fi
+
+  # Step 7: Append new config
+  {
+    echo ""
+    echo "# OCP LAN (added by ocp connect)"
+    echo "export OPENAI_BASE_URL=$base_url/v1"
+    if [[ -n "$key" ]]; then
+      echo "export OPENAI_API_KEY=$key"
+    fi
+  } >> "$rc_file"
+
+  echo "  Written to $rc_file:"
+  echo "    OPENAI_BASE_URL=$base_url/v1"
+  if [[ -n "$key" ]]; then
+    echo "    OPENAI_API_KEY=${key:0:8}..."
+  fi
+  echo ""
+
+  # Step 8: Quick smoke test — send a minimal chat completion
+  echo "  Running smoke test..."
+  local chat_payload='{"model":"claude-haiku-4-5-20251001","messages":[{"role":"user","content":"Reply with OK only."}],"max_tokens":10}'
+  local chat_out chat_ok=0
+  if [[ -n "$key" ]]; then
+    chat_out=$(curl -sf --max-time 30 \
+      -H "Authorization: Bearer $key" \
+      -H "Content-Type: application/json" \
+      -d "$chat_payload" \
+      "$base_url/v1/chat/completions" 2>/dev/null) && chat_ok=1
+  else
+    chat_out=$(curl -sf --max-time 30 \
+      -H "Content-Type: application/json" \
+      -d "$chat_payload" \
+      "$base_url/v1/chat/completions" 2>/dev/null) && chat_ok=1
+  fi
+
+  if [[ $chat_ok -eq 1 ]]; then
+    local reply
+    reply=$(echo "$chat_out" | python3 -c "import sys,json; d=json.loads(sys.stdin.read()); print(d['choices'][0]['message']['content'].strip())" 2>/dev/null || echo "(response received)")
+    echo "  ✓ Smoke test passed: $reply"
+  else
+    echo "  ⚠ Smoke test failed (proxy is reachable but chat completion did not succeed)."
+    echo "    The env vars have still been written. Check the remote OCP logs."
+  fi
+
+  echo ""
+  echo "  Done. Reload your shell to apply:"
+  echo "    source $rc_file"
+}
+
+# ── lan ─────────────────────────────────────────────────────────────────
+cmd_lan_help() {
+  cat <<'EOF'
+ocp lan — Quick LAN mode setup guide
+
+Shows current network configuration and connection instructions
+for other devices on the same network.
+
+Usage: ocp lan
+EOF
+}
+
+cmd_lan() {
+  local ip
+  ip=$(ipconfig getifaddr en0 2>/dev/null || ipconfig getifaddr en1 2>/dev/null || hostname -I 2>/dev/null | awk '{print $1}' || echo "unknown")
+  local port=3456
+
+  echo "OCP LAN Setup"
+  echo "─────────────────────────────────────"
+  echo ""
+  echo "  Your IP: $ip"
+  echo "  Port:    $port"
+  echo ""
+  echo "  For IDE users, set:"
+  echo "    OPENAI_BASE_URL=http://$ip:$port/v1"
+  echo "    OPENAI_API_KEY=<your-key>    (if auth enabled)"
+  echo ""
+  echo "  Dashboard: http://$ip:$port/dashboard"
+  echo ""
+
+  if curl -sf --max-time 2 "http://$ip:$port/health" > /dev/null 2>&1; then
+    echo "  Status: ✓ LAN-accessible"
+  else
+    echo "  Status: ✗ Not LAN-accessible (bound to localhost only)"
+    echo ""
+    echo "  To enable LAN mode, set env var and restart:"
+    echo "    CLAUDE_BIND=0.0.0.0"
+    echo "    ocp restart"
+  fi
+}
+
+# ── restart ──────────────────────────────────────────────────────────────
+cmd_restart_help() {
+  cat <<'EOF'
+ocp restart — Restart the proxy or gateway
+
+Usage:
+  ocp restart            Restart the Claude proxy service
+  ocp restart gateway    Restart the OpenClaw gateway
+                         (briefly disconnects all Telegram/Discord bots)
+EOF
+}
+
+cmd_restart() {
+  if [[ "${1:-}" == "gateway" ]]; then
+    echo "Restarting gateway..."
+    openclaw gateway restart 2>&1
+  else
+    echo "Restarting proxy..."
+    # Try current service name, then legacy, then manual restart
+    local uid
+    uid=$(id -u)
+    if launchctl kickstart -k "gui/$uid/dev.ocp.proxy" 2>/dev/null; then
+      true
+    elif launchctl kickstart -k "gui/$uid/ai.openclaw.proxy" 2>/dev/null; then
+      true
+    elif systemctl --user restart ocp-proxy 2>/dev/null; then
+      true
+    elif systemctl --user restart openclaw-proxy 2>/dev/null; then
+      true
+    else
+      echo "Service restart failed, trying kill + restart..."
+      pkill -f "server.mjs.*CLAUDE_PROXY" 2>/dev/null || pkill -f "claude-proxy/server.mjs" 2>/dev/null || true
+      sleep 1
+      local self_r script_dir
+      self_r="${BASH_SOURCE[0]}"
+      while [[ -L "$self_r" ]]; do self_r="$(readlink "$self_r")"; done
+      script_dir="$(cd "$(dirname "$self_r")" && pwd)"
+      DISABLE_AUTOUPDATER=1 nohup node "$script_dir/server.mjs" >> "$HOME/.ocp/logs/proxy.log" 2>&1 &
+    fi
+    sleep 3
+    if curl -sf --max-time 5 "$PROXY/health" > /dev/null 2>&1; then
+      echo "✓ Proxy restarted successfully."
+      cmd_usage
+    else
+      echo "✗ Proxy not responding after restart."
+    fi
+  fi
+}
+
+# ── settings ─────────────────────────────────────────────────────────────
+cmd_settings_help() {
+  cat <<'EOF'
+ocp settings — View or update proxy settings at runtime
+
+Usage:
+  ocp settings                   Show all tunable settings
+  ocp settings <key> <value>     Update a setting (no restart needed)
+
+Tunable keys:
+  timeout            Overall request timeout (ms)         [30000 - 600000]
+  firstByteTimeout   Base first-byte timeout (ms)         [15000 - 300000]
+  maxConcurrent      Max concurrent claude processes      [1 - 32]
+  sessionTTL         Session idle expiry (ms)             [60000 - 86400000]
+  maxPromptChars     Prompt truncation limit (chars)      [10000 - 1000000]
+  tiers.opus.base    Opus first-byte timeout base (ms)    [30000 - 600000]
+  tiers.opus.perChar    Opus per-char timeout (ms/char)   [0 - 0.01]
+  tiers.sonnet.base  Sonnet first-byte timeout base (ms)  [30000 - 600000]
+  tiers.sonnet.perChar  Sonnet per-char timeout (ms/char) [0 - 0.01]
+  tiers.haiku.base   Haiku first-byte timeout base (ms)   [15000 - 300000]
+  tiers.haiku.perChar   Haiku per-char timeout (ms/char)  [0 - 0.01]
+
+Examples:
+  ocp settings maxPromptChars 200000
+  ocp settings tiers.sonnet.base 150000
+EOF
+}
+
+cmd_settings() {
+  if [[ -z "${1:-}" ]]; then
+    # GET — show all settings
+    curl -sf --max-time 5 "$PROXY/settings" | python3 -c "
+import sys, json
+d = json.loads(sys.stdin.read())
+print('OCP Settings')
+print('─────────────────────────────────────')
+for k in ('timeout','firstByteTimeout','maxConcurrent','sessionTTL','maxPromptChars'):
+    v = d.get(k, {})
+    val = v.get('value', '?')
+    unit = v.get('unit', '')
+    desc = v.get('desc', '')
+    print(f'  {k:<20} {val:>8} {unit:<6}  {desc}')
+t = d.get('tiers', {})
+print()
+print('Timeout Tiers (first-byte):')
+for tier in ('opus','sonnet','haiku'):
+    info = t.get(tier, {})
+    print(f'  {tier:<8} base={info.get(\"base\",\"?\"):>6}ms  perChar={info.get(\"perPromptChar\",\"?\")}')
+"
+  elif [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
+    cmd_settings_help
+  elif [[ -z "${2:-}" ]]; then
+    echo "Usage: ocp settings <key> <value>"
+    echo "Run 'ocp settings --help' for available keys."
+    return 1
+  else
+    # PATCH — update a setting
+    local key="$1"
+    local value="$2"
+    local result
+    result=$(curl -s --max-time 5 -X PATCH "$PROXY/settings" \
+      -H "Content-Type: application/json" \
+      -d "{\"$key\": $value}" 2>&1)
+    if echo "$result" | python3 -c "import sys,json; d=json.loads(sys.stdin.read()); errs=d.get('errors',[]); exit(1 if errs else 0)" 2>/dev/null; then
+      echo "✓ $key = $value"
+    else
+      echo "$result" | python3 -c "
+import sys, json
+d = json.loads(sys.stdin.read())
+for e in d.get('errors', []):
+    print(f'✗ {e}')
+" 2>/dev/null || echo "✗ $result"
+    fi
+  fi
+}
+
+# ── update ──────────────────────────────────────────────────────────────
+cmd_update_help() {
+  cat <<'EOF'
+ocp update — Smart upgrade dispatcher
+
+Runs `ocp doctor` internally to choose the right path:
+  • Patch bump (same minor):     light path (git pull + npm install + restart)
+  • Cross-minor (e.g. v3.10→v3.14): full path with snapshot + post-flight
+  • Old version (< v3.4.0):       fresh-install (asks first; AI passes --yes)
+
+Usage:
+  ocp update                          Smart auto-pick path
+  ocp update --check                  Show available updates, don't apply
+  ocp update --dry-run                Preview the plan, don't mutate
+  ocp update --target v3.13.0         Pin a specific version
+  ocp update --yes                    Skip y/N prompts (AI agents pass this)
+  ocp update --rollback               Restore the most recent upgrade snapshot
+  ocp update --rollback --list        List available snapshots
+  ocp update --rollback <path>        Restore a specific snapshot
+  ocp update --rollback --dry-run     Preview rollback plan
+  ocp update --rollback --gc          Delete old snapshots (keep last 5, or <30 days)
+  ocp update --rollback --gc --dry-run    Preview what would be deleted
+EOF
+}
+
+cmd_update() {
+  local script_dir self
+  self="${BASH_SOURCE[0]}"
+  while [[ -L "$self" ]]; do self="$(readlink "$self")"; done
+  script_dir="$(cd "$(dirname "$self")" && pwd)"
+
+  # Pass through --check fast path (existing behaviour)
+  if [[ "${1:-}" == "--check" ]]; then
+    cd "$script_dir"
+    git fetch origin main --quiet 2>/dev/null || true
+    local local_ver remote_ver
+    local_ver=$(python3 -c "import json; print(json.load(open('package.json'))['version'])" 2>/dev/null || echo "?")
+    remote_ver=$(git show origin/main:package.json 2>/dev/null | python3 -c "import sys,json; print(json.load(sys.stdin)['version'])" 2>/dev/null || echo "?")
+    local behind
+    behind=$(git rev-list HEAD..origin/main --count 2>/dev/null || echo "?")
+    echo "OCP Update Check"
+    echo "─────────────────────────────────────"
+    echo "  Current:  v$local_ver"
+    echo "  Latest:   v$remote_ver"
+    if [[ "$behind" == "0" ]]; then
+      echo "  Status:   ✓ Up to date"
+    else
+      echo "  Status:   $behind commit(s) behind"
+      echo "  Run 'ocp update' to apply."
+    fi
+    return 0
+  fi
+
+  # Rollback path
+  if [[ "${1:-}" == "--rollback" ]]; then
+    shift
+    exec node "$script_dir/scripts/upgrade.mjs" --rollback "$@"
+  fi
+
+  # Doctor-driven path selection
+  local kind
+  kind=$(node "$script_dir/scripts/doctor.mjs" --json 2>/dev/null | python3 -c "import sys,json; print(json.load(sys.stdin)['next_action']['kind'])" 2>/dev/null || echo "unknown")
+
+  case "$kind" in
+    noop)
+      echo "Already at latest. Nothing to do."
+      return 0
+      ;;
+    update)
+      _cmd_update_light "$script_dir"
+      ;;
+    upgrade|fresh_install)
+      exec node "$script_dir/scripts/upgrade.mjs" "$@"
+      ;;
+    fix_oauth|fix_service)
+      echo "Pre-upgrade check failed: $kind"
+      echo "Run \`ocp doctor\` for details and ai_executable steps."
+      return 1
+      ;;
+    *)
+      echo "Unknown doctor kind: $kind. Run \`ocp doctor --json\` to inspect."
+      return 1
+      ;;
+  esac
+}
+
+# Existing light-path body extracted into a helper so cmd_update can call it conditionally.
+_cmd_update_light() {
+  local script_dir="$1"
+  echo "Updating OCP (light path)..."
+  cd "$script_dir"
+  local old_ver new_ver
+  old_ver=$(python3 -c "import json; print(json.load(open('package.json'))['version'])" 2>/dev/null || echo "?")
+  echo "  Pulling latest from GitHub..."
+  if ! git pull origin main --ff-only 2>&1 | sed 's/^/    /'; then
+    echo "  ✗ Git pull failed. Resolve conflicts manually in: $script_dir"
+    return 1
+  fi
+  new_ver=$(python3 -c "import json; print(json.load(open('package.json'))['version'])" 2>/dev/null || echo "?")
+  if [[ "$old_ver" == "$new_ver" ]]; then
+    echo "  ✓ Already at latest (v$new_ver)"
+  else
+    echo "  ✓ Updated v$old_ver → v$new_ver"
+  fi
+
+  # Sync plugin (existing logic preserved)
+  local ext_dir="$HOME/.openclaw/extensions/ocp"
+  if [[ -d "$ext_dir" && -d "$script_dir/ocp-plugin" ]]; then
+    echo "  Syncing OCP plugin..."
+    cp "$script_dir/ocp-plugin/index.js" "$ext_dir/index.js" 2>/dev/null
+    cp "$script_dir/ocp-plugin/package.json" "$ext_dir/package.json" 2>/dev/null
+    cp "$script_dir/ocp-plugin/openclaw.plugin.json" "$ext_dir/openclaw.plugin.json" 2>/dev/null
+    echo "  ✓ Plugin synced"
+  fi
+
+  if command -v node >/dev/null 2>&1 && [[ -f "$script_dir/scripts/sync-openclaw.mjs" ]]; then
+    echo "  Syncing OpenClaw registry..."
+    node "$script_dir/scripts/sync-openclaw.mjs" 2>&1 | sed 's/^/    /' || echo "  ⚠ OpenClaw sync failed (non-fatal)"
+  fi
+
+  echo "  Restarting proxy..."
+  cmd_restart > /dev/null 2>&1
+}
+
+cmd_doctor_help() {
+  cat <<'EOF'
+ocp doctor — Health & upgrade-readiness check
+
+Runs a series of checks (Node version, git state, service health,
+OAuth token, plist customisation, OpenClaw provider) and emits either
+human-readable PASS/WARN/FAIL output or a JSON next_action that
+AI agents can execute.
+
+Usage:
+  ocp doctor              Human-readable output
+  ocp doctor --json       JSON for AI agents and ocp update internal use
+  ocp doctor --check oauth    Fast path: OAuth check only
+EOF
+}
+
+cmd_doctor() {
+  local script_dir self
+  self="${BASH_SOURCE[0]}"
+  while [[ -L "$self" ]]; do self="$(readlink "$self")"; done
+  script_dir="$(cd "$(dirname "$self")" && pwd)"
+  exec node "$script_dir/scripts/doctor.mjs" "$@"
+}
+
+# ── help ─────────────────────────────────────────────────────────────────
+cmd_help() {
+  cat <<'EOF'
+ocp — OpenClaw Proxy CLI
+
+Usage: ocp <command> [args]
+
+Commands:
+  usage              Plan usage limits (--by-key for per-key stats)
+  status             Quick overview (usage + health)
+  health             Proxy diagnostics
+  settings           View or update tunable settings
+  logs [N] [level]   Recent logs (default: 20, error)
+  models             Available models
+  sessions           Active sessions
+  clear              Clear all sessions
+  keys               Manage API keys (add/list/revoke)
+  lan                LAN mode setup guide
+  connect <ip>       Connect to a remote OCP (sets env vars in rc file)
+  restart            Restart proxy
+  restart gateway    Restart gateway
+  update             Update OCP to latest version
+  update --check     Check for updates
+
+Run 'ocp <command> --help' for details on a specific command.
+EOF
+}
+
+# ── dispatch ─────────────────────────────────────────────────────────────
+# Check for --help/-h on any subcommand: ocp <cmd> --help
+subcmd="${1:-help}"
+shift 2>/dev/null || true
+
+# Global --help
+if [[ "$subcmd" == "--help" || "$subcmd" == "-h" || "$subcmd" == "help" ]]; then
+  cmd_help
+  exit 0
+fi
+
+# Per-subcommand --help
+for arg in "$@"; do
+  if [[ "$arg" == "--help" || "$arg" == "-h" ]]; then
+    fn="cmd_${subcmd}_help"
+    if declare -f "$fn" > /dev/null 2>&1; then
+      "$fn"
+    else
+      echo "No help available for '$subcmd'."
+    fi
+    exit 0
+  fi
+done
+
+case "$subcmd" in
+  usage)    cmd_usage "${1:-}" ;;
+  status)   cmd_status ;;
+  health)   cmd_health ;;
+  settings) cmd_settings "${1:-}" "${2:-}" ;;
+  logs)     cmd_logs "${1:-20}" "${2:-error}" ;;
+  models)   cmd_models ;;
+  sessions) cmd_sessions ;;
+  clear)    cmd_clear ;;
+  keys)     cmd_keys "${1:-}" "${2:-}" ;;
+  lan)      cmd_lan ;;
+  connect)  cmd_connect "$@" ;;
+  restart)  cmd_restart "${1:-}" ;;
+  doctor)   cmd_doctor "$@" ;;
+  update)   cmd_update "$@" ;;
+  *)        echo "Unknown command: $subcmd"; echo ""; cmd_help; exit 1 ;;
+esac

ocp-connect

@@ -0,0 +1,721 @@
+#!/usr/bin/env bash
+# ocp-connect — Lightweight client script to connect to a remote OCP instance
+# No dependencies beyond curl and python3 (available on most Linux/Mac systems)
+#
+# Install:
+#   curl -fsSL https://raw.githubusercontent.com/dtzp555-max/ocp/main/ocp-connect -o ocp-connect
+#   chmod +x ocp-connect
+#
+# Or run directly:
+#   curl -fsSL https://raw.githubusercontent.com/dtzp555-max/ocp/main/ocp-connect | bash -s -- <host-ip> --key <key>
+#
+set -euo pipefail
+
+OCP_CONNECT_VERSION="1.3.0"
+
+show_version() {
+  echo "ocp-connect $OCP_CONNECT_VERSION"
+}
+
+show_help() {
+  cat <<'EOF'
+ocp-connect — Connect this machine to a remote OCP (Open Claude Proxy)
+
+Configures OPENAI_BASE_URL and OPENAI_API_KEY in your shell rc file
+so tools like Claude Code, Cline, Aider, etc. point to the remote OCP.
+
+Usage:
+  ocp-connect <host-ip> [options]
+
+Options:
+  --port PORT      Port OCP listens on (default: 3456)
+  --key  API_KEY   API key (prompted interactively if remote requires auth)
+  --version        Print version and exit
+  --help, -h       Show this help
+
+Examples:
+  ocp-connect 192.168.1.10
+  ocp-connect 192.168.1.10 --port 8080
+  ocp-connect 192.168.1.10 --key ocp_abc123
+
+What it does:
+  1. Tests connectivity to the remote OCP
+  2. Verifies your API key (if auth is enabled)
+  3. Writes OPENAI_BASE_URL and OPENAI_API_KEY to ~/.bashrc or ~/.zshrc
+  4. Sets system-level env vars (launchctl on macOS, systemd on Linux)
+  5. Configures OpenClaw automatically; prints setup hints for other IDEs
+     (Cline, Continue.dev, Cursor — manual configuration required)
+  6. Runs a smoke test to confirm everything works
+
+After running, reload your shell:  source ~/.bashrc  (or ~/.zshrc)
+EOF
+}
+
+configure_ides() {
+  local base_url="$1" key="$2" models_out="$3"
+
+  # --- OpenClaw ---
+  local oc_config="$HOME/.openclaw/openclaw.json"
+  local oc_found=false
+  if command -v openclaw &>/dev/null || [[ -f "$oc_config" ]]; then
+    oc_found=true
+  fi
+
+  if $oc_found; then
+    echo "  IDE Configuration"
+    echo "  ─────────────────────────────────────"
+    echo "  Detected: OpenClaw ($oc_config)"
+    echo ""
+    printf "  Configure OpenClaw to use this OCP? [Y/n] "
+    local oc_answer
+    { read -r oc_answer </dev/tty; } 2>/dev/null || oc_answer="y"
+    oc_answer="${oc_answer:-y}"
+
+    if [[ "$oc_answer" =~ ^[Yy]$ ]]; then
+      # Ask for provider name
+      printf "  Provider name (models show as <name>/model-id) [ocp]: "
+      local provider_name
+      { read -r provider_name </dev/tty; } 2>/dev/null || provider_name=""
+      provider_name="${provider_name:-ocp}"
+      # Sanitize: only allow alphanumeric, dash, underscore
+      provider_name=$(echo "$provider_name" | tr -cd 'a-zA-Z0-9_-')
+      [[ -z "$provider_name" ]] && provider_name="ocp"
+
+      # Ask for priority
+      echo ""
+      echo "  How should OCP models be configured?"
+      echo "    1) Primary — use OCP by default, keep existing models as backup"
+      echo "    2) Backup  — keep current primary, add OCP as additional option"
+      echo ""
+      printf "  Choice [1]: "
+      local priority_choice
+      { read -r priority_choice </dev/tty; } 2>/dev/null || priority_choice="1"
+      priority_choice="${priority_choice:-1}"
+
+      echo ""
+      echo "  Writing OpenClaw config..."
+
+      # Use python3 to safely manipulate JSON
+      local py_ok=0
+      python3 - "$oc_config" "$base_url" "$key" "$provider_name" "$priority_choice" "$models_out" <<'PYEOF' && py_ok=1
+import sys, json, os
+
+config_path = sys.argv[1]
+base_url = sys.argv[2]
+api_key = sys.argv[3]
+provider_name = sys.argv[4]
+priority = sys.argv[5]  # "1" = primary, "2" = backup
+models_json_str = sys.argv[6]
+
+# Parse models from OCP /v1/models response
+try:
+    models_data = json.loads(models_json_str)
+    model_ids = [m["id"] for m in models_data.get("data", [])]
+except:
+    model_ids = ["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4"]
+
+# Build provider entry
+provider = {
+    "baseUrl": base_url + "/v1",
+    "api": "openai-completions",
+    "authHeader": bool(api_key),
+    "models": []
+}
+
+# Model metadata mapping (prefix match for versioned IDs like claude-haiku-4-5-20251001)
+model_meta = {
+    "claude-opus-4": {"name": "Claude Opus (OCP)", "reasoning": True, "maxTokens": 16384},
+    "claude-sonnet-4": {"name": "Claude Sonnet (OCP)", "reasoning": True, "maxTokens": 16384},
+    "claude-haiku-4": {"name": "Claude Haiku (OCP)", "reasoning": False, "maxTokens": 8192},
+}
+
+def get_model_meta(mid):
+    """Match model metadata by prefix."""
+    for prefix, meta in sorted(model_meta.items(), key=lambda x: -len(x[0])):
+        if mid.startswith(prefix):
+            return meta
+    return {"name": mid + " (OCP)", "reasoning": False, "maxTokens": 8192}
+
+for mid in model_ids:
+    meta = get_model_meta(mid)
+    provider["models"].append({
+        "id": mid,
+        "name": meta["name"],
+        "reasoning": meta["reasoning"],
+        "input": ["text"],
+        "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
+        "contextWindow": 200000,
+        "maxTokens": meta["maxTokens"]
+    })
+
+# Load or create config
+if os.path.exists(config_path):
+    with open(config_path, "r") as f:
+        config = json.load(f)
+else:
+    os.makedirs(os.path.dirname(config_path), exist_ok=True)
+    config = {}
+
+# Ensure models.providers exists
+config.setdefault("models", {})
+config["models"].setdefault("mode", "merge")
+config["models"].setdefault("providers", {})
+
+# Remove any previous OCP provider with the same name
+config["models"]["providers"][provider_name] = provider
+
+# Set up auth profile if key is provided
+if api_key:
+    config.setdefault("auth", {})
+    config["auth"].setdefault("profiles", {})
+    config["auth"]["profiles"][provider_name + ":default"] = {
+        "provider": provider_name,
+        "mode": "api_key"
+    }
+
+# Configure agent defaults — add model aliases
+config.setdefault("agents", {})
+config["agents"].setdefault("defaults", {})
+config["agents"]["defaults"].setdefault("models", {})
+
+# Build alias map (prefix match)
+alias_prefixes = {
+    "claude-opus-4": "Claude Opus",
+    "claude-sonnet-4": "Claude Sonnet",
+    "claude-haiku-4": "Claude Haiku",
+}
+
+for mid in model_ids:
+    full_id = provider_name + "/" + mid
+    alias = mid  # fallback
+    for prefix, name in sorted(alias_prefixes.items(), key=lambda x: -len(x[0])):
+        if mid.startswith(prefix):
+            alias = name
+            break
+    config["agents"]["defaults"]["models"][full_id] = {"alias": alias}
+
+# Handle primary/backup
+if priority == "1":
+    # OCP as primary — pick the best model (prefer sonnet for daily use)
+    primary_model = provider_name + "/claude-sonnet-4-6" if "claude-sonnet-4-6" in model_ids else provider_name + "/" + model_ids[0]
+    config["agents"]["defaults"].setdefault("model", {})
+    config["agents"]["defaults"]["model"]["primary"] = primary_model
+    # Keep existing fallbacks
+    config["agents"]["defaults"]["model"].setdefault("fallbacks", [])
+
+# If backup (priority == "2"), don't change the primary — just add models to the list
+
+# Update agent list entries that use old provider name patterns
+# (only update if agents.list exists and has entries using old OCP-like providers)
+if "list" in config.get("agents", {}):
+    for agent in config["agents"]["list"]:
+        agent_model = agent.get("model", {})
+        if priority == "1" and agent_model.get("primary", "").startswith("claude-local/"):
+            # Migrate from claude-local to new provider
+            old_model_id = agent_model["primary"].split("/", 1)[1]
+            if old_model_id in model_ids:
+                agent_model["primary"] = provider_name + "/" + old_model_id
+        # Also update subagents if they use claude-local
+        sub = agent.get("subagents", config["agents"]["defaults"].get("subagents", {}))
+        # Don't modify subagents in agent entries — they inherit from defaults
+
+# Update defaults subagents model if using claude-local
+if priority == "1":
+    sub = config["agents"]["defaults"].get("subagents", {})
+    if sub.get("model", "").startswith("claude-local/"):
+        old_id = sub["model"].split("/", 1)[1]
+        if old_id in model_ids:
+            sub["model"] = provider_name + "/" + old_id
+
+with open(config_path, "w") as f:
+    json.dump(config, f, indent=2, ensure_ascii=False)
+    f.write("\n")
+
+# === B1 fix: seed per-agent auth-profiles.json for OpenClaw multi-agent setups ===
+# OpenClaw's per-agent auth loader reads <agentDir>/auth-profiles.json (NOT the
+# root openclaw.json's auth.profiles section). Without a real key in each agent's
+# agentDir, OpenClaw rejects the lane with "No API key found for provider X".
+# See https://github.com/dtzp555-max/ocp/issues/12 for the full investigation.
+_seeded = []
+_failed = []
+_skipped_anonymous = []
+_profile_key = provider_name + ":default"
+# OpenClaw stores per-agent auth in <openclaw_root>/agents/<id>/agent/ when
+# the agent has no explicit `agentDir` field — derive that path so the
+# default `main` agent (which never sets agentDir) is also seeded.
+_openclaw_root = os.path.dirname(config_path)
+for _agent in config.get("agents", {}).get("list", []):
+    _agent_dir = _agent.get("agentDir")
+    if not _agent_dir:
+        _agent_id = _agent.get("id")
+        if not _agent_id:
+            continue
+        _agent_dir = os.path.join(_openclaw_root, "agents", _agent_id, "agent")
+    if not api_key:
+        # Anonymous mode is incompatible with OpenClaw per-agent auth (empty key
+        # is dropped by OpenClaw's pi-auth-credentials). Per OCP issue #12 §14
+        # decision: take Path C (require --key for OpenClaw multi-agent setups).
+        _skipped_anonymous.append(_agent_dir)
+        continue
+    _profiles_path = os.path.join(_agent_dir, "auth-profiles.json")
+    try:
+        os.makedirs(_agent_dir, exist_ok=True)
+    except OSError as _e:
+        _failed.append((_profiles_path, "mkdir: " + str(_e)))
+        continue
+    if os.path.exists(_profiles_path):
+        try:
+            with open(_profiles_path) as _f:
+                _ap = json.load(_f)
+        except json.JSONDecodeError:
+            # Corrupted JSON — back up and rebuild from scratch.
+            _bak = _profiles_path + ".bak"
+            try:
+                os.rename(_profiles_path, _bak)
+                print(f"    ⚠ {_profiles_path} was corrupt; backed up to {_bak}")
+            except OSError:
+                pass
+            _ap = {"version": 1, "profiles": {}}
+        except OSError as _e:
+            # Read failure (permissions, disk) — skip to AVOID clobbering
+            # the user's existing profile (which may hold other providers' keys).
+            _failed.append((_profiles_path, "read: " + str(_e)))
+            continue
+    else:
+        _ap = {"version": 1, "profiles": {}}
+    _ap.setdefault("version", 1)
+    _ap.setdefault("profiles", {})
+    _ap["profiles"][_profile_key] = {
+        "type": "api_key",
+        "provider": provider_name,
+        "key": api_key
+    }
+    try:
+        with open(_profiles_path, "w") as _f:
+            json.dump(_ap, _f, indent=2, ensure_ascii=False)
+            _f.write("\n")
+        os.chmod(_profiles_path, 0o600)
+        _seeded.append(_profiles_path)
+    except OSError as _e:
+        _failed.append((_profiles_path, "write: " + str(_e)))
+
+# Report — all three sections are independent (mixed scenarios are surfaced).
+if _seeded:
+    print(f"    ✓ Per-agent auth profile seeded ({len(_seeded)}):")
+    for _p in _seeded:
+        print(f"      • {_p}")
+if _failed:
+    print(f"    ⚠ Per-agent auth profile FAILED ({len(_failed)}):")
+    for _p, _err in _failed:
+        print(f"      • {_p}: {_err}")
+    print("      OpenClaw will report \"No API key found\" for the failed agents.")
+    print("      Fix the underlying error (permissions / disk) and re-run ocp-connect.")
+if _skipped_anonymous:
+    print(f"    ⚠ OpenClaw multi-agent mode detected ({len(_skipped_anonymous)} agents).")
+    print("      Anonymous mode does not work for OpenClaw per-agent auth.")
+    print("      Re-run with: ocp-connect <host> --key ocp_xxx")
+PYEOF
+
+      if [[ $py_ok -eq 1 ]]; then
+        echo "  ✓ OpenClaw configured"
+        echo "    Provider: $provider_name"
+        echo "    Models:"
+        # List models from the already-fetched models_out
+        echo "$models_out" | python3 -c "
+import sys,json
+d=json.loads(sys.stdin.read())
+pn='$provider_name'
+for m in d.get('data',[]):
+    print('      • ' + pn + '/' + m['id'])
+" 2>/dev/null
+        if [[ "$priority_choice" == "1" ]]; then
+          echo "    Priority: PRIMARY (default model)"
+        else
+          echo "    Priority: BACKUP (available in model selector)"
+        fi
+        echo ""
+        echo "    Restart OpenClaw to apply: openclaw gateway restart"
+      else
+        echo "  ⚠ Failed to write OpenClaw config. You can configure it manually."
+      fi
+    else
+      echo "  Skipped OpenClaw configuration."
+    fi
+    echo ""
+  fi
+
+  # --- Other IDEs: print manual instructions ---
+  local other_ides_shown=false
+
+  # Collect VS Code extension list once (reused by Cline and Continue.dev checks)
+  local _vscode_exts=""
+  if command -v code &>/dev/null; then
+    _vscode_exts=$(code --list-extensions 2>/dev/null || true)
+  fi
+  if [[ -z "$_vscode_exts" && -d "$HOME/.vscode/extensions" ]]; then
+    _vscode_exts=$(ls "$HOME/.vscode/extensions/" 2>/dev/null || true)
+  fi
+
+  # Extract model IDs from /v1/models response for use in hints
+  local _model_ids
+  _model_ids=$(echo "$models_out" | python3 -c "
+import sys,json
+try:
+    d=json.loads(sys.stdin.read())
+    print(', '.join(m['id'] for m in d.get('data', [])))
+except Exception:
+    print('claude-sonnet-4-6, claude-opus-4-6, claude-haiku-4-5-20251001')
+" 2>/dev/null || echo "claude-sonnet-4-6, claude-opus-4-6, claude-haiku-4-5-20251001")
+
+  # Key display: truncate if longer than 16 chars to avoid screenshot leakage,
+  # show explicit "(none)" in anonymous mode so users don't paste blank fields.
+  local _key_display
+  if [[ -z "$key" ]]; then
+    _key_display="(none — anonymous mode; most external IDEs require a non-empty API Key)"
+  elif [[ ${#key} -gt 16 ]]; then
+    _key_display="${key:0:8}...${key: -4}"
+  else
+    _key_display="$key"
+  fi
+
+  # Detect Cline (VS Code extension saoudrizwan.claude-dev, see issue #12)
+  if echo "$_vscode_exts" | grep -qiE 'cline|saoudrizwan\.claude-dev'; then
+    if ! $other_ides_shown; then
+      echo "  Other IDEs detected:"
+      other_ides_shown=true
+    fi
+    echo "    • Cline: VSCode → Cline panel → Settings → API Provider = \"OpenAI Compatible\""
+    echo "        Base URL: $base_url/v1"
+    echo "        API Key:  $_key_display"
+    echo "        Model ID: $_model_ids"
+  fi
+
+  # Detect Continue.dev (extension ID continue.continue or config file, see issue #12)
+  if echo "$_vscode_exts" | grep -qi 'continue\.continue' \
+     || [[ -f "$HOME/.continue/config.yaml" ]] \
+     || [[ -f "$HOME/.continue/config.json" ]]; then
+    if ! $other_ides_shown; then
+      echo "  Other IDEs detected:"
+      other_ides_shown=true
+    fi
+    echo "    • Continue.dev: edit ~/.continue/config.yaml — add under \`models:\` (top-level key):"
+    echo "        models:"
+    echo "          - name: OCP Sonnet"
+    echo "            provider: openai"
+    echo "            model: claude-sonnet-4-6"
+    echo "            apiBase: $base_url/v1"
+    echo "            apiKey: $_key_display"
+    echo "        (other model IDs: $_model_ids)"
+  fi
+
+  # Detect Cursor (command, ~/.cursor dir, or /Applications/Cursor.app, see issue #12)
+  if command -v cursor &>/dev/null \
+     || [[ -d "$HOME/.cursor" ]] \
+     || [[ -d "/Applications/Cursor.app" ]]; then
+    if ! $other_ides_shown; then
+      echo "  Other IDEs detected:"
+      other_ides_shown=true
+    fi
+    echo "    • Cursor: Cmd+Shift+P → 'Cursor Settings' → Models →"
+    echo "        OpenAI API Key:           $_key_display"
+    echo "        Override OpenAI Base URL: $base_url/v1"
+    echo "        Custom OpenAI Models:     $_model_ids"
+  fi
+
+  # Detect opencode (https://opencode.ai, SST team CLI, see issue #12)
+  if command -v opencode &>/dev/null \
+     || [[ -x "$HOME/.opencode/bin/opencode" ]] \
+     || [[ -d "$HOME/.local/share/opencode" ]]; then
+    if ! $other_ides_shown; then
+      echo "  Other IDEs detected:"
+      other_ides_shown=true
+    fi
+    echo "    • opencode: not yet auto-configured by ocp-connect (PR follow-up)."
+    echo "        Run \`opencode providers login openai\` and provide:"
+    echo "          Base URL: $base_url/v1"
+    echo "          API Key:  $_key_display"
+    echo "        Available model IDs: $_model_ids"
+  fi
+
+  if $other_ides_shown; then
+    echo ""
+  fi
+}
+
+main() {
+  local host="" port=3456 key=""
+
+  # Parse args
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --port)  port="${2:?'--port requires a value'}"; shift 2 ;;
+      --key)   key="${2:?'--key requires a value'}"
+               [[ -z "$key" ]] && { echo "Error: --key cannot be empty (omit --key entirely for anonymous mode)"; exit 1; }
+               shift 2 ;;
+      --version) show_version; exit 0 ;;
+      --help|-h) show_help; exit 0 ;;
+      -*)      echo "Unknown option: $1"; show_help; exit 1 ;;
+      *)       host="$1"; shift ;;
+    esac
+  done
+
+  if [[ -z "$host" ]]; then
+    echo "Error: host IP is required."
+    echo ""
+    show_help
+    exit 1
+  fi
+
+  if ! [[ "$host" =~ ^[a-zA-Z0-9._-]+$ ]]; then
+    echo "Error: invalid host '$host'"
+    exit 1
+  fi
+
+  # Check dependencies
+  for cmd in curl python3; do
+    if ! command -v "$cmd" &>/dev/null; then
+      echo "Error: '$cmd' is required but not found."
+      exit 1
+    fi
+  done
+
+  local base_url="http://$host:$port"
+
+  echo "OCP Connect v$OCP_CONNECT_VERSION"
+  echo "─────────────────────────────────────"
+  echo "  Remote: $base_url"
+  echo ""
+
+  # Step 1: Test connectivity via /health
+  echo "  Checking connectivity..."
+  local health_json
+  health_json=$(curl -sf --max-time 10 "$base_url/health" 2>/dev/null) || {
+    echo "  ✗ Cannot reach $base_url/health"
+    echo "    Make sure OCP is running on $host and bound to 0.0.0.0 (LAN mode)."
+    exit 1
+  }
+  echo "  ✓ Connected"
+  echo ""
+
+  # Step 2: Show remote info
+  local remote_version auth_mode
+  remote_version=$(echo "$health_json" | python3 -c "import sys,json; d=json.loads(sys.stdin.read()); print(d.get('version','?'))" 2>/dev/null || echo "?")
+  auth_mode=$(echo "$health_json" | python3 -c "import sys,json; d=json.loads(sys.stdin.read()); print(d.get('authMode','none'))" 2>/dev/null || echo "none")
+
+  echo "  Remote OCP v$remote_version  (auth: $auth_mode)"
+  echo ""
+
+  # Step 2.5: auto-discover anonymous key from /health (issue #12 §14 Path A).
+  # When the OCP admin set PROXY_ANONYMOUS_KEY, the server advertises it via
+  # /health.anonymousKey. If the user didn't pass --key, use it automatically so
+  # `ocp-connect <host>` works zero-config for OpenClaw multi-agent setups.
+  if [[ -z "$key" ]]; then
+    local anon_key
+    anon_key=$(echo "$health_json" | python3 -c "
+import sys, json
+try:
+    d = json.loads(sys.stdin.read())
+    k = d.get('anonymousKey')
+except Exception:
+    k = None
+print(k if k else '')
+" 2>/dev/null || echo "")
+    if [[ -n "$anon_key" ]]; then
+      key="$anon_key"
+      local _anon_display="$anon_key"
+      if [[ ${#anon_key} -gt 16 ]]; then
+        _anon_display="${anon_key:0:8}...${anon_key: -4}"
+      fi
+      echo "  ⓘ Using server-advertised anonymous key: $_anon_display"
+      echo "    (set by admin via PROXY_ANONYMOUS_KEY; see issue #12 §14 Path A)"
+      echo ""
+    fi
+  fi
+
+  # Step 3: Determine if key is needed
+  if [[ "$auth_mode" != "none" && -z "$key" ]]; then
+    # Try anonymous access first (zero-config: server may allow it)
+    if curl -sf --max-time 5 "$base_url/v1/models" >/dev/null 2>&1; then
+      echo "  Server allows anonymous access — no key needed."
+      echo ""
+    else
+      echo "  Remote requires authentication."
+      echo "  Ask the OCP admin to run:  ocp keys add <name>"
+      printf "  Enter API key (or press Enter to skip): "
+      { read -rs key </dev/tty; } 2>/dev/null || key=""
+      echo
+      if [[ -z "$key" ]]; then
+        echo ""
+        echo "  ✗ No key provided — cannot connect to an auth-required remote without a key."
+        echo "    Use:  ocp-connect $host --key <key>"
+        exit 1
+      fi
+    fi
+  fi
+
+  # Step 4: Test API access via /v1/models
+  echo "  Testing API access..."
+  local models_out models_ok=0
+  if [[ -n "$key" ]]; then
+    models_out=$(curl -sf --max-time 10 \
+      -H "Authorization: Bearer $key" \
+      "$base_url/v1/models" 2>/dev/null) && models_ok=1
+  else
+    models_out=$(curl -sf --max-time 10 "$base_url/v1/models" 2>/dev/null) && models_ok=1
+  fi
+
+  if [[ $models_ok -eq 0 ]]; then
+    echo "  ✗ API access failed — key may be invalid or revoked."
+    exit 1
+  fi
+  local model_count
+  model_count=$(echo "$models_out" | python3 -c "import sys,json; print(len(json.loads(sys.stdin.read()).get('data',[])))" 2>/dev/null || echo "?")
+  echo "  ✓ API accessible ($model_count models available)"
+  echo ""
+
+  # Step 5: Detect shell rc files and OS
+  local rc_files=()
+  local is_mac=false
+  [[ "$(uname)" == "Darwin" ]] && is_mac=true
+
+  # Write to all relevant rc files
+  if [[ "${SHELL:-}" == */fish ]]; then
+    echo "  Note: fish shell detected. Writing to ~/.bashrc — add to fish config manually."
+    rc_files+=("$HOME/.bashrc")
+  elif $is_mac; then
+    # macOS: default shell since Catalina (2019) is zsh.
+    # Always write ~/.zshrc (create if absent — zsh tolerates an empty file).
+    # Only write ~/.bashrc if it already exists (don't surprise users with new files).
+    [[ -f "$HOME/.bashrc" ]] && rc_files+=("$HOME/.bashrc")
+    # zshrc: always include on macOS; create the file if it doesn't exist yet
+    [[ -f "$HOME/.zshrc" ]] || touch "$HOME/.zshrc"
+    rc_files+=("$HOME/.zshrc")
+  else
+    # Linux / other: write to whichever rc files already exist or match current shell
+    [[ -f "$HOME/.bashrc" || "${SHELL:-}" == */bash ]] && rc_files+=("$HOME/.bashrc")
+    [[ -f "$HOME/.zshrc" || "${SHELL:-}" == */zsh ]] && rc_files+=("$HOME/.zshrc")
+    # If neither exists, fall back to creating one for the current shell
+    [[ ${#rc_files[@]} -eq 0 ]] && rc_files+=("$HOME/.${SHELL##*/}rc")
+  fi
+
+  # Step 6: Remove any previously written OCP LAN lines (idempotent) from all rc files
+  for rc_file in "${rc_files[@]}"; do
+    if [[ -f "$rc_file" ]]; then
+      local tmp_rc
+      tmp_rc=$(mktemp)
+      if python3 - "$rc_file" "$tmp_rc" <<'PYEOF'
+import sys
+src, dst = sys.argv[1], sys.argv[2]
+lines = open(src).readlines()
+out = []
+skip = False
+for line in lines:
+    s = line.rstrip('\n')
+    if s == '# OCP LAN (added by ocp connect)':
+        skip = True
+        continue
+    if skip and (s == '' or s.startswith('export OPENAI_BASE_URL=') or s.startswith('export OPENAI_API_KEY=')):
+        continue
+    skip = False
+    out.append(line)
+open(dst, 'w').writelines(out)
+PYEOF
+      then
+        cp "$tmp_rc" "$rc_file"
+      fi
+      rm -f "$tmp_rc"
+    fi
+  done
+
+  # Step 7: Append new config to all rc files
+  for rc_file in "${rc_files[@]}"; do
+    {
+      echo ""
+      echo "# OCP LAN (added by ocp connect)"
+      echo "export OPENAI_BASE_URL=$base_url/v1"
+      if [[ -n "$key" ]]; then
+        echo "export OPENAI_API_KEY=$key"
+      fi
+    } >> "$rc_file"
+  done
+
+  echo "  Shell config:"
+  for rc_file in "${rc_files[@]}"; do
+    echo "    ✓ $(basename "$rc_file")"
+  done
+  echo "    OPENAI_BASE_URL=$base_url/v1"
+  if [[ -n "$key" ]]; then
+    echo "    OPENAI_API_KEY=${key:0:8}..."
+  fi
+
+  # Step 7b: System-level env vars (for IDEs, daemons, GUI apps)
+  if $is_mac; then
+    # macOS: launchctl setenv makes vars visible to all GUI apps and launchd services
+    launchctl setenv OPENAI_BASE_URL "$base_url/v1" 2>/dev/null
+    if [[ -n "$key" ]]; then
+      launchctl setenv OPENAI_API_KEY "$key" 2>/dev/null
+    fi
+    echo ""
+    echo "  System-level (launchctl):"
+    echo "    ✓ OPENAI_BASE_URL set for GUI apps and daemons"
+    echo "    Note: launchctl vars reset on reboot. Add to Login Items or re-run ocp-connect."
+  else
+    # Linux: write to environment.d for systemd user services
+    local env_dir="$HOME/.config/environment.d"
+    mkdir -p "$env_dir" 2>/dev/null
+    {
+      echo "OPENAI_BASE_URL=$base_url/v1"
+      if [[ -n "$key" ]]; then
+        echo "OPENAI_API_KEY=$key"
+      fi
+    } > "$env_dir/ocp.conf"
+    echo ""
+    echo "  System-level (systemd):"
+    echo "    ✓ $env_dir/ocp.conf"
+    echo "    Applies to systemd user services after re-login."
+  fi
+  echo ""
+
+  # Step 7c: Interactive IDE configuration
+  configure_ides "$base_url" "$key" "$models_out"
+
+  # Step 8: Quick smoke test
+  echo "  Running smoke test..."
+  # Pick the first available model from /v1/models
+  local smoke_model
+  smoke_model=$(echo "$models_out" | python3 -c "import sys,json; d=json.loads(sys.stdin.read()); print(d['data'][0]['id'])" 2>/dev/null || echo "claude-haiku-4-5-20251001")
+  local chat_payload="{\"model\":\"$smoke_model\",\"messages\":[{\"role\":\"user\",\"content\":\"Reply with OK only.\"}],\"max_tokens\":10}"
+  local chat_out chat_ok=0
+  if [[ -n "$key" ]]; then
+    chat_out=$(curl -sf --max-time 30 \
+      -H "Authorization: Bearer $key" \
+      -H "Content-Type: application/json" \
+      -d "$chat_payload" \
+      "$base_url/v1/chat/completions" 2>/dev/null) && chat_ok=1
+  else
+    chat_out=$(curl -sf --max-time 30 \
+      -H "Content-Type: application/json" \
+      -d "$chat_payload" \
+      "$base_url/v1/chat/completions" 2>/dev/null) && chat_ok=1
+  fi
+
+  if [[ $chat_ok -eq 1 ]]; then
+    local reply
+    reply=$(echo "$chat_out" | python3 -c "import sys,json; d=json.loads(sys.stdin.read()); print(d['choices'][0]['message']['content'].strip())" 2>/dev/null || echo "(response received)")
+    echo "  ✓ Smoke test passed: $reply"
+    echo "    Note: smoke test only verifies OCP is reachable and the key is valid."
+    echo "    It does not verify your IDE/agent end-to-end. To verify OpenClaw works,"
+    echo "    restart it (\`openclaw gateway restart\`) and send a test message to your bot."
+  else
+    echo "  ⚠ Smoke test failed (proxy is reachable but chat completion did not succeed)."
+    echo "    The env vars have still been written. Check the remote OCP logs."
+  fi
+
+  echo ""
+  echo "  Done. Reload your shell to apply:"
+  for rc_file in "${rc_files[@]}"; do
+    echo "    source $rc_file"
+  done
+}
+
+main "$@"

ocp-plugin/index.js

@@ -0,0 +1,311 @@
+/**
+ * OCP Plugin — registers /ocp as a native slash command in OpenClaw gateway.
+ * Calls the local claude-proxy and formats the response.
+ *
+ * Port resolution (in priority order):
+ *   1. OCP_PROXY_URL env (full URL, e.g. http://10.0.0.5:3456)
+ *   2. CLAUDE_PROXY_PORT env (port only; localhost assumed)
+ *   3. Fallback: http://127.0.0.1:3456 (OCP server source default since v1.0)
+ *
+ * If a particular host's OCP plist injects a non-default CLAUDE_PROXY_PORT,
+ * the OpenClaw launchd plist for that host must also inject the same
+ * CLAUDE_PROXY_PORT into the plugin's env, or the plugin will fall back to
+ * 3456 and miss the server.
+ */
+const PROXY = process.env.OCP_PROXY_URL
+  || (process.env.CLAUDE_PROXY_PORT ? `http://127.0.0.1:${process.env.CLAUDE_PROXY_PORT}` : "http://127.0.0.1:3456");
+
+// Wrap output in monospace code block for Telegram/Discord alignment
+function mono(text) { return "```\n" + text + "\n```"; }
+
+async function fetchJSON(path) {
+  const resp = await fetch(`${PROXY}${path}`, { signal: AbortSignal.timeout(15000) });
+  if (!resp.ok) throw new Error(`proxy ${resp.status}: ${resp.statusText}`);
+  return resp.json();
+}
+
+function bar(pct, width = 16) {
+  const filled = Math.round(pct * width);
+  return "█".repeat(filled) + "░".repeat(width - filled);
+}
+
+function fmtMs(ms) {
+  return ms >= 1000 ? `${(ms / 1000).toFixed(0)}s` : `${ms}ms`;
+}
+
+function fmtChars(c) {
+  return c >= 1000 ? `${(c / 1000).toFixed(0)}K` : `${c}`;
+}
+
+// ── Subcommand handlers ─────────────────────────────────────────────────
+
+async function cmdUsage() {
+  const d = await fetchJSON("/usage");
+  const plan = d.plan || {};
+  const s = plan.currentSession || {};
+  const w = plan.weeklyLimits?.allModels || {};
+  const e = plan.extraUsage || {};
+  const px = d.proxy;
+  const models = d.models || {};
+
+  let out = "";
+
+  // Show subscription info if available
+  if (plan.subscription) {
+    out += `Plan: ${plan.subscription} (${plan.rateLimitTier || "default"})\n`;
+  }
+
+  if (s.utilization !== null && s.utilization !== undefined) {
+    // Full plan usage data available (API key mode)
+    out += "Plan Usage Limits\n";
+    out += "─────────────────────────────\n";
+    out += `Current session   ${bar(s.utilization)} ${s.percent}\n`;
+    out += `                  Resets in ${s.resetsIn}  (${s.resetsAtHuman})\n\n`;
+    out += `Weekly (all)      ${bar(w.utilization)} ${w.percent}\n`;
+    out += `                  Resets in ${w.resetsIn}  (${w.resetsAtHuman})\n\n`;
+    out += `Extra usage       ${e.status === "allowed" ? "on" : "off"}\n\n`;
+  } else {
+    // No API key — show note
+    out += "Session/weekly %: claude.ai/settings\n";
+    out += "(Anthropic OAuth API doesn't expose limits yet)\n\n";
+  }
+
+  const modelNames = Object.keys(models).sort();
+  if (modelNames.length > 0) {
+    out += "Model Stats\n";
+    const hdr = `${"Model".padEnd(14)} ${"Req".padStart(4)} ${"OK".padStart(3)} ${"Er".padStart(3)} ${"AvgT".padStart(5)} ${"MaxT".padStart(5)} ${"AvgP".padStart(5)} ${"MaxP".padStart(5)}`;
+    out += hdr + "\n";
+    out += "─".repeat(hdr.length) + "\n";
+    let total = 0;
+    for (const name of modelNames) {
+      const m = models[name];
+      total += m.requests;
+      const short = name.replace("claude-", "").replace("-4-5-20251001", "").replace("-4-6", "");
+      out += `${short.padEnd(14)} ${String(m.requests).padStart(4)} ${String(m.successes).padStart(3)} ${String(m.errors).padStart(3)} ${fmtMs(m.avgElapsed).padStart(5)} ${fmtMs(m.maxElapsed).padStart(5)} ${fmtChars(m.avgPromptChars).padStart(5)} ${fmtChars(m.maxPromptChars).padStart(5)}\n`;
+    }
+    out += `${"Total".padEnd(14)} ${String(total).padStart(4)}\n`;
+  }
+
+  out += `\nProxy: up ${px.uptime} | ${px.totalRequests} reqs | ${px.errors} err | ${px.timeouts} timeout`;
+  return out;
+}
+
+async function cmdHealth() {
+  const d = await fetchJSON("/health");
+  let out = `Status: ${d.status} | v${d.version}\n`;
+  out += `Uptime: ${d.uptimeHuman}\n`;
+  out += `Auth: ${d.auth?.ok ? "ok" : d.auth?.message || "unknown"}\n`;
+  out += `Binary: ${d.claudeBinaryOk ? "ok" : "missing"}\n`;
+  out += `Sessions: ${d.sessions?.length || 0} active\n`;
+  out += `Requests: ${d.stats?.totalRequests || 0} total, ${d.stats?.activeRequests || 0} active\n`;
+  out += `Errors: ${d.stats?.errors || 0} | Timeouts: ${d.stats?.timeouts || 0}\n`;
+  if (d.recentErrors?.length) {
+    out += "\nRecent errors:\n";
+    for (const e of d.recentErrors.slice(-3)) {
+      out += `  ${e.time?.slice(11, 19) || "?"} ${e.message}\n`;
+    }
+  }
+  return out;
+}
+
+async function cmdStatus() {
+  const d = await fetchJSON("/status");
+  const icon = d.proxy?.status === "ok" ? "🟢" : d.proxy?.status === "degraded" ? "🟡" : "🔴";
+  let out = `${icon} ${d.proxy?.status} | v${d.proxy?.version} | up ${d.proxy?.uptime} | auth ${d.proxy?.auth}\n`;
+  out += `Sessions: ${d.proxy?.activeSessions || 0}\n`;
+  out += `Requests: ${d.requests?.total || 0} | active ${d.requests?.active || 0} | err ${d.requests?.errors || 0} | timeout ${d.requests?.timeouts || 0}\n`;
+  if (d.plan?.currentSession) {
+    out += `\nSession: ${d.plan.currentSession.percent} (resets ${d.plan.currentSession.resetsIn})\n`;
+    out += `Weekly:  ${d.plan.weeklyLimits?.allModels?.percent} (resets ${d.plan.weeklyLimits?.allModels?.resetsIn})`;
+  }
+  return out;
+}
+
+async function cmdSettings(args) {
+  if (!args) {
+    const d = await fetchJSON("/settings");
+    let out = "OCP Settings\n─────────────────────────────\n";
+    for (const k of ["timeout", "firstByteTimeout", "maxConcurrent", "sessionTTL", "maxPromptChars"]) {
+      const v = d[k];
+      if (v) out += `${k.padEnd(20)} ${String(v.value).padStart(8)} ${(v.unit || "").padEnd(6)} ${v.desc}\n`;
+    }
+    if (d.tiers) {
+      out += "\nTimeout tiers:\n";
+      for (const t of ["opus", "sonnet", "haiku"]) {
+        const info = d.tiers[t];
+        if (info) out += `  ${t.padEnd(8)} base=${info.base}ms  perChar=${info.perPromptChar}\n`;
+      }
+    }
+    return out;
+  }
+
+  // Parse "key value"
+  const parts = args.trim().split(/\s+/);
+  if (parts.length < 2 || parts[0] === "--help" || parts[0] === "-h") {
+    return "Usage: /ocp settings <key> <value>\nKeys: timeout, firstByteTimeout, maxConcurrent, sessionTTL, maxPromptChars, tiers.opus.base, tiers.sonnet.base, tiers.haiku.base, tiers.*.perChar";
+  }
+  const [key, val] = parts;
+  const numVal = Number(val);
+  if (isNaN(numVal)) return `Error: value must be a number, got "${val}"`;
+
+  const resp = await fetch(`${PROXY}/settings`, {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ [key]: numVal }),
+    signal: AbortSignal.timeout(5000),
+  });
+  const d = await resp.json();
+  if (d.errors?.length) return `✗ ${d.errors.join("; ")}`;
+  return `✓ ${key} = ${numVal}`;
+}
+
+async function cmdModels() {
+  const d = await fetchJSON("/v1/models");
+  return (d.data || []).map((m) => `  ${m.id}`).join("\n") || "No models.";
+}
+
+async function cmdSessions() {
+  const d = await fetchJSON("/sessions");
+  if (!d.sessions?.length) return "No active sessions.";
+  return d.sessions.map((s) => `  ${s.id.slice(0, 16)}… model=${s.model} msgs=${s.messages}`).join("\n");
+}
+
+async function cmdClear() {
+  const resp = await fetch(`${PROXY}/sessions`, { method: "DELETE", signal: AbortSignal.timeout(5000) });
+  const d = await resp.json();
+  return `Cleared ${d.cleared} sessions.`;
+}
+
+async function cmdVersion() {
+  const d = await fetchJSON("/health");
+  return `OCP v${d.version || "?"}\nUptime: ${d.uptimeHuman || "?"}\nNode: ${process.version}\nPlatform: ${process.platform} ${process.arch}`;
+}
+
+async function cmdTest() {
+  const t0 = Date.now();
+  try {
+    const resp = await fetch(`${PROXY}/v1/chat/completions`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: "claude-haiku-4-5-20251001",
+        messages: [{ role: "user", content: "say ok" }],
+        max_tokens: 5,
+      }),
+      signal: AbortSignal.timeout(30000),
+    });
+    const d = await resp.json();
+    const elapsed = Date.now() - t0;
+    if (d.choices?.[0]?.message?.content) {
+      return `✓ Proxy OK (${elapsed}ms)\n  Model: haiku\n  Response: "${d.choices[0].message.content.slice(0, 50)}"`;
+    }
+    return `✗ Unexpected response: ${JSON.stringify(d).slice(0, 100)}`;
+  } catch (e) {
+    return `✗ Test failed (${Date.now() - t0}ms): ${e.message}`;
+  }
+}
+
+async function cmdRestart(args) {
+  const target = (args || "").trim().toLowerCase();
+  const { execSync } = await import("node:child_process");
+  try {
+    if (target === "gateway") {
+      execSync("launchctl kickstart -k gui/501/ai.openclaw.gateway", { timeout: 15000 });
+      return "✓ Gateway restarted";
+    } else if (target === "all") {
+      execSync("launchctl kickstart -k gui/501/ai.openclaw.proxy", { timeout: 15000 });
+      // Gateway restart will kill this plugin too, so do it last
+      execSync("launchctl kickstart -k gui/501/ai.openclaw.gateway", { timeout: 15000 });
+      return "✓ Proxy + Gateway restarted";
+    } else {
+      execSync("launchctl kickstart -k gui/501/ai.openclaw.proxy", { timeout: 15000 });
+      return "✓ Proxy restarted";
+    }
+  } catch (e) {
+    // Try systemd for Linux
+    try {
+      if (target === "gateway") {
+        execSync("systemctl --user restart openclaw-gateway", { timeout: 15000 });
+        return "✓ Gateway restarted";
+      } else {
+        execSync("systemctl --user restart openclaw-proxy 2>/dev/null || pkill -f 'node.*server.mjs' && sleep 2 && cd ~/.openclaw/projects/*/; node server.mjs &", { timeout: 15000, shell: true });
+        return "✓ Proxy restarted";
+      }
+    } catch (e2) {
+      return `✗ Restart failed: ${e2.message?.slice(0, 100)}`;
+    }
+  }
+}
+
+async function cmdLogs(args) {
+  const parts = (args || "").trim().split(/\s+/);
+  const n = parseInt(parts[0]) || 20;
+  const level = parts[1] || "error";
+  const d = await fetchJSON(`/logs?n=${n}&level=${level}`);
+  if (!d.entries?.length) return `No ${level} log entries.`;
+  return d.entries.map((e) => {
+    if (e.raw) return e.raw.slice(0, 120);
+    return `${(e.ts || "").slice(11, 19)} ${(e.level || "").toUpperCase()} ${e.event || "?"} ${e.model || ""}`;
+  }).join("\n");
+}
+
+function cmdHelp() {
+  return `OCP Commands
+─────────────────────────────
+/ocp usage              Plan usage & model stats
+/ocp status             Quick overview
+/ocp health             Proxy diagnostics
+/ocp settings           View tunable settings
+/ocp settings <k> <v>   Update a setting
+/ocp logs [N] [level]   Recent logs (default: 20, error)
+/ocp models             Available models
+/ocp sessions           Active sessions
+/ocp clear              Clear all sessions
+/ocp restart            Restart proxy
+/ocp restart gateway    Restart gateway
+/ocp restart all        Restart both
+/ocp version            Version & platform info
+/ocp test               End-to-end proxy test`;
+}
+
+// ── Plugin entry point ──────────────────────────────────────────────────
+
+export default function (api) {
+  console.log("[ocp] OCP plugin loading, registering /ocp command...");
+  api.registerCommand({
+    name: "ocp",
+    description: "OpenClaw Proxy commands — usage, health, settings, logs, etc.",
+    acceptsArgs: true,
+    requireAuth: true,
+    handler: async (ctx) => {
+      const raw = (ctx.args || "").trim();
+      const spaceIdx = raw.indexOf(" ");
+      const subcmd = spaceIdx === -1 ? raw : raw.slice(0, spaceIdx);
+      const subargs = spaceIdx === -1 ? "" : raw.slice(spaceIdx + 1).trim();
+
+      try {
+        let text;
+        switch (subcmd) {
+          case "usage":    text = await cmdUsage(); break;
+          case "health":   text = await cmdHealth(); break;
+          case "status":   text = await cmdStatus(); break;
+          case "settings": text = await cmdSettings(subargs || null); break;
+          case "models":   text = await cmdModels(); break;
+          case "sessions": text = await cmdSessions(); break;
+          case "clear":    text = await cmdClear(); break;
+          case "restart":  text = await cmdRestart(subargs); break;
+          case "version":  text = await cmdVersion(); break;
+          case "test":     text = await cmdTest(); break;
+          case "logs":     text = await cmdLogs(subargs); break;
+          case "help": case "--help": case "-h": case "":
+            text = cmdHelp(); break;
+          default:
+            text = `Unknown subcommand: ${subcmd}\n\n${cmdHelp()}`;
+        }
+        return { text: mono(text) };
+      } catch (err) {
+        return { text: `OCP error: ${err.message}` };
+      }
+    },
+  });
+}

ocp-plugin/openclaw.plugin.json

@@ -0,0 +1,17 @@
+{
+  "id": "ocp",
+  "name": "OCP Commands",
+  "description": "Slash commands for the OpenClaw Proxy — /ocp usage, /ocp settings, /ocp health, etc.",
+  "version": "3.16.2",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "proxyUrl": {
+        "type": "string",
+        "default": "http://127.0.0.1:3456",
+        "description": "URL of the Claude proxy. Overridable via OCP_PROXY_URL or CLAUDE_PROXY_PORT env."
+      }
+    }
+  }
+}

ocp-plugin/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "ocp",
+  "version": "3.12.0",
+  "description": "Slash commands for the OpenClaw Proxy",
+  "main": "index.js",
+  "type": "module",
+  "keywords": ["openclaw", "plugin", "ocp", "proxy"],
+  "license": "MIT",
+  "openclaw": {
+    "type": "plugin",
+    "id": "ocp",
+    "pluginManifest": "openclaw.plugin.json"
+  }
+}

openclaw-claude-proxy/README.md

@@ -1,182 +0,0 @@
-# openclaw-claude-proxy v2.3.0
-
-Use your **Claude Pro / Max** subscription as an **OpenAI-compatible local endpoint**.
-
-`openclaw-claude-proxy` accepts OpenAI-style chat completion requests, then runs them through the local `claude` CLI. That means tools which only know how to talk to an OpenAI API can still use Claude models through a local base URL.
-
-## Why v2 matters
-
-v2 is not just a bugfix release. It changes the runtime model:
-
-- **On-demand spawning** instead of fragile warm pools
-- **Session resume** support for multi-turn conversations
-- **Faster fallback** with first-byte timeout + lower default request timeout
-- **Full tool access** via configurable allowed tools
-- **MCP config + system prompt pass-through**
-- **Health / sessions / diagnostics endpoints**
-- **Safe coexistence with Claude Code channel / interactive mode**
-
-## The short pitch
-
-If Claude's new channel workflow feels useful, OCP v2 now covers the same practical ground for many local agent/tooling setups:
-
-- multi-turn continuity
-- tool-enabled Claude runs
-- local orchestration
-- stable process isolation
-- coexistence with your normal Claude Code workflow
-
-And it adds a few advantages that channel users usually still want:
-
-- **OpenAI-compatible HTTP API** for existing tools
-- **Works with OpenClaw, Cursor, Continue, Open WebUI, LangChain, and anything with custom base URL support**
-- **Explicit health checks and diagnostics**
-- **Model/provider failover can happen outside Claude itself**
-- **No lock-in to a single client UX**
-
-## Coexistence with Claude Code channel
-
-This is the important part: **OCP v2 does not replace Claude Code channel, and it does not need to. They can coexist on the same machine.**
-
-### Claude Code channel / interactive mode
-- persistent interactive workflow
-- MCP protocol / in-process experience
-- great when you are directly driving Claude Code
-
-### OCP v2
-- local HTTP server on `localhost`
-- OpenAI-compatible API surface
-- per-request `claude -p` execution with session resume when you want continuity
-- ideal for external tools, routers, orchestrators, OpenClaw providers, and local automation
-
-### Practical takeaway
-Use both:
-- use **Claude Code channel** when you want Claude's native interactive workflow
-- use **OCP v2** when another app expects an OpenAI-style API but you still want to use Claude
-
-They solve adjacent problems, not identical ones.
-
-## Unique advantages of OCP v2
-
-1. **API compatibility**
-   - Drop into tools that already support OpenAI-compatible endpoints.
-   - No need to wait for each tool to add native Claude channel support.
-
-2. **Routing freedom**
-   - Put OCP behind OpenClaw or another router.
-   - Mix Claude with fallback providers outside the Claude client itself.
-
-3. **Operational visibility**
-   - `/health`, `/sessions`, recent errors, auth state, resolved binary path, timeout config.
-   - Much easier to debug than a black-box local integration.
-
-4. **Safer runtime model**
-   - v2 removes the old pre-spawn pool crash loop.
-   - No stale workers, no degraded warm pool states, fewer hidden failure modes.
-
-5. **Configurable tools and behavior**
-   - allowed tools
-   - skip permissions mode
-   - system prompt append
-   - MCP config passthrough
-   - session TTL
-   - concurrency limits
-
-## Install
-
-```bash
-git clone https://github.com/dtzp555-max/openclaw-claude-proxy
-cd openclaw-claude-proxy
-npm install
-node server.mjs
-```
-
-Default base URL:
-
-```text
-http://127.0.0.1:3456/v1
-```
-
-## Quick OpenAI-compatible config
-
-```json
-{
-  "baseURL": "http://127.0.0.1:3456/v1",
-  "apiKey": "anything"
-}
-```
-
-If `PROXY_API_KEY` is unset, auth is disabled. If you set it, pass it as a Bearer token.
-
-## Environment variables
-
-| Variable | Default | Purpose |
-|---|---:|---|
-| `CLAUDE_PROXY_PORT` | `3456` | Listen port |
-| `CLAUDE_BIN` | auto-detect | Claude CLI binary path |
-| `CLAUDE_TIMEOUT` | `120000` | Overall per-request timeout |
-| `CLAUDE_FIRST_BYTE_TIMEOUT` | `30000` | Abort if Claude produces no stdout quickly |
-| `CLAUDE_ALLOWED_TOOLS` | expanded set | Comma-separated allowed tools |
-| `CLAUDE_SKIP_PERMISSIONS` | `false` | Bypass permission checks |
-| `CLAUDE_SYSTEM_PROMPT` | unset | Append a system prompt to every request |
-| `CLAUDE_MCP_CONFIG` | unset | Path to MCP config JSON |
-| `CLAUDE_SESSION_TTL` | `3600000` | Session TTL |
-| `CLAUDE_MAX_CONCURRENT` | `5` | Max concurrent Claude processes |
-| `PROXY_API_KEY` | unset | Optional Bearer token auth |
-
-## Endpoints
-
-- `GET /health`
-- `GET /v1/models`
-- `POST /v1/chat/completions`
-- `GET /sessions`
-- `DELETE /sessions`
-
-## Example health response highlights
-
-`/health` reports useful operational state such as:
-
-- resolved Claude binary path
-- whether the binary is executable
-- auth status
-- timeouts
-- current sessions
-- recent errors
-- basic request stats
-
-## Version highlights
-
-### v2.3.0
-- clarified v2 positioning and coexistence story in docs
-- officially documents faster fallback defaults
-- recommends OCP v2 as the API bridge layer for Claude-powered tools
-
-### v2.2.0
-- first-byte timeout
-- reduced default timeout for faster fallback
-
-### v2.0.0
-- on-demand architecture
-- session management
-- full tool access
-- MCP + system prompt passthrough
-- concurrency control
-- coexistence with Claude Code interactive mode
-
-## When to use OCP v2 vs Claude channel
-
-Choose **OCP v2** when:
-- your app only supports OpenAI-compatible endpoints
-- you want routing / failover outside Claude
-- you want explicit health checks and local diagnostics
-- you want Claude available to multiple local tools through one endpoint
-
-Choose **Claude channel** when:
-- you are primarily living inside Claude Code itself
-- you want Claude's native interactive workflow directly
-
-Use **both together** when you want the best of both worlds.
-
----
-
-If you already pay for Claude Pro or Max, OCP v2 turns that subscription into a practical local API bridge for the rest of your tooling stack.

openclaw-claude-proxy/package.json

@@ -1,28 +0,0 @@
-{
-  "name": "openclaw-claude-proxy",
-  "version": "2.3.0",
-  "description": "OpenAI-compatible proxy for Claude CLI v2 — on-demand sessions, faster fallback, and safe coexistence with Claude Code channels",
-  "type": "module",
-  "bin": {
-    "openclaw-claude-proxy": "./server.mjs"
-  },
-  "scripts": {
-    "start": "node server.mjs",
-    "setup": "node setup.mjs"
-  },
-  "keywords": [
-    "openclaw",
-    "claude",
-    "proxy",
-    "openai",
-    "anthropic"
-  ],
-  "license": "MIT",
-  "engines": {
-    "node": ">=18"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/dtzp555-max/openclaw-claude-proxy"
-  }
-}

openclaw-claude-proxy/server.mjs

@@ -1,549 +0,0 @@
-#!/usr/bin/env node
-/**
- * openclaw-claude-proxy v2.3.0 — OpenAI-compatible proxy for Claude CLI
- *
- * Translates OpenAI chat/completions requests into `claude -p` CLI calls,
- * letting you use your Claude Pro/Max subscription as an OpenClaw model provider.
- *
- * v2.0.0 highlights:
- *   - On-demand spawning: eliminates pool crash loops from v1.x
- *   - Session management: --resume support reduces token waste on multi-turn
- *   - Full tool access: configurable allowedTools (expanded defaults)
- *   - System prompt & MCP config pass-through
- *   - Concurrency control with queuing
- *   - Coexists safely with Claude Code interactive mode (Telegram, IDE, etc.)
- *
- * Env vars:
- *   CLAUDE_PROXY_PORT        — listen port (default: 3456)
- *   CLAUDE_BIN               — path to claude binary (default: auto-detect)
- *   CLAUDE_TIMEOUT           — per-request timeout in ms (default: 120000)
- *   CLAUDE_FIRST_BYTE_TIMEOUT — abort if no stdout within this ms (default: 30000)
- *   CLAUDE_ALLOWED_TOOLS     — comma-separated tools to allow (default: expanded set)
- *   CLAUDE_SKIP_PERMISSIONS  — "true" to bypass all permission checks (default: false)
- *   CLAUDE_SYSTEM_PROMPT     — system prompt appended to all requests
- *   CLAUDE_MCP_CONFIG        — path to MCP server config JSON file
- *   CLAUDE_SESSION_TTL       — session TTL in ms (default: 3600000 = 1h)
- *   CLAUDE_MAX_CONCURRENT    — max concurrent claude processes (default: 5)
- *   PROXY_API_KEY            — Bearer token for API auth (optional)
- */
-import { createServer } from "node:http";
-import { spawn, execFileSync } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import { readFileSync, accessSync, constants } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const _pkg = JSON.parse(readFileSync(join(__dirname, "package.json"), "utf8"));
-
-// ── Resolve claude binary ───────────────────────────────────────────────
-// Priority: CLAUDE_BIN env > well-known paths > which lookup
-// Fail-fast if not found — never start with an unresolvable binary.
-function resolveClaude() {
-  if (process.env.CLAUDE_BIN) {
-    try {
-      accessSync(process.env.CLAUDE_BIN, constants.X_OK);
-      return process.env.CLAUDE_BIN;
-    } catch {
-      console.error(`FATAL: CLAUDE_BIN="${process.env.CLAUDE_BIN}" is set but not executable.`);
-      process.exit(1);
-    }
-  }
-
-  const candidates = [
-    "/opt/homebrew/bin/claude",
-    "/usr/local/bin/claude",
-    "/usr/bin/claude",
-    join(process.env.HOME || "", ".local/bin/claude"),
-  ];
-  for (const p of candidates) {
-    try { accessSync(p, constants.X_OK); console.warn(`[init] CLAUDE_BIN not set, resolved to ${p}`); return p; } catch {}
-  }
-
-  try {
-    const resolved = execFileSync("which", ["claude"], { encoding: "utf8", timeout: 5000 }).trim();
-    if (resolved) { console.warn(`[init] CLAUDE_BIN not set, resolved via which: ${resolved}`); return resolved; }
-  } catch {}
-
-  console.error(
-    "FATAL: claude binary not found.\n" +
-    "  Set CLAUDE_BIN=/path/to/claude or ensure claude is in PATH.\n" +
-    "  Checked: " + candidates.join(", ")
-  );
-  process.exit(1);
-}
-
-// ── Configuration ───────────────────────────────────────────────────────
-const PORT = parseInt(process.env.CLAUDE_PROXY_PORT || "3456", 10);
-const CLAUDE = resolveClaude();
-const TIMEOUT = parseInt(process.env.CLAUDE_TIMEOUT || "120000", 10);
-const FIRST_BYTE_TIMEOUT = parseInt(process.env.CLAUDE_FIRST_BYTE_TIMEOUT || "30000", 10);
-const PROXY_API_KEY = process.env.PROXY_API_KEY || "";
-const SKIP_PERMISSIONS = process.env.CLAUDE_SKIP_PERMISSIONS === "true";
-const ALLOWED_TOOLS = (process.env.CLAUDE_ALLOWED_TOOLS ||
-  "Bash,Read,Write,Edit,Glob,Grep,WebSearch,WebFetch,Agent"
-).split(",").map(s => s.trim()).filter(Boolean);
-const SYSTEM_PROMPT = process.env.CLAUDE_SYSTEM_PROMPT || "";
-const MCP_CONFIG = process.env.CLAUDE_MCP_CONFIG || "";
-const SESSION_TTL = parseInt(process.env.CLAUDE_SESSION_TTL || "3600000", 10);
-const MAX_CONCURRENT = parseInt(process.env.CLAUDE_MAX_CONCURRENT || "5", 10);
-
-const VERSION = _pkg.version;
-const START_TIME = Date.now();
-
-// ── Model mapping ───────────────────────────────────────────────────────
-// Maps request model IDs and aliases to canonical claude CLI model IDs.
-const MODEL_MAP = {
-  "claude-opus-4-6": "claude-opus-4-6",
-  "claude-sonnet-4-6": "claude-sonnet-4-6",
-  "claude-haiku-4-5-20251001": "claude-haiku-4-5-20251001",
-  "claude-opus-4": "claude-opus-4-6",
-  "claude-haiku-4": "claude-haiku-4-5-20251001",
-  "claude-haiku-4-5": "claude-haiku-4-5-20251001",
-  "opus": "claude-opus-4-6",
-  "sonnet": "claude-sonnet-4-6",
-  "haiku": "claude-haiku-4-5-20251001",
-};
-
-const MODELS = [
-  { id: "claude-opus-4-6", name: "Claude Opus 4.6" },
-  { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6" },
-  { id: "claude-haiku-4-5-20251001", name: "Claude Haiku 4.5" },
-];
-
-// ── Session management ──────────────────────────────────────────────────
-// Maps conversation IDs (from caller) to Claude CLI session UUIDs.
-// Enables --resume for multi-turn conversations, reducing token waste.
-const sessions = new Map(); // conversationId → { uuid, messageCount, lastUsed, model }
-
-setInterval(() => {
-  const now = Date.now();
-  for (const [id, s] of sessions) {
-    if (now - s.lastUsed > SESSION_TTL) {
-      sessions.delete(id);
-      console.log(`[session] expired ${id.slice(0, 12)}... (idle ${Math.round((now - s.lastUsed) / 60000)}m)`);
-    }
-  }
-}, 60000);
-
-// ── Stats & diagnostics ─────────────────────────────────────────────────
-const stats = {
-  totalRequests: 0,
-  activeRequests: 0,
-  errors: 0,
-  timeouts: 0,
-  sessionHits: 0,
-  sessionMisses: 0,
-  oneOffRequests: 0,
-};
-const recentErrors = []; // last 20 errors
-
-function trackError(msg) {
-  stats.errors++;
-  recentErrors.push({ time: new Date().toISOString(), message: String(msg).slice(0, 200) });
-  if (recentErrors.length > 20) recentErrors.shift();
-}
-
-// ── Auth health check ───────────────────────────────────────────────────
-let authStatus = { ok: null, lastCheck: 0, message: "" };
-
-async function checkAuth() {
-  try {
-    const env = { ...process.env };
-    delete env.CLAUDECODE;
-    delete env.ANTHROPIC_API_KEY;
-    delete env.ANTHROPIC_BASE_URL;
-    delete env.ANTHROPIC_AUTH_TOKEN;
-    execFileSync(CLAUDE, ["auth", "status"], { encoding: "utf8", timeout: 10000, env });
-    authStatus = { ok: true, lastCheck: Date.now(), message: "authenticated" };
-  } catch (e) {
-    const msg = (e.stderr || e.message || "").slice(0, 200);
-    authStatus = { ok: false, lastCheck: Date.now(), message: msg };
-    console.error(`[auth] check failed: ${msg}`);
-  }
-}
-
-// Check auth on start and every 10 minutes
-checkAuth();
-setInterval(checkAuth, 600000);
-
-// ── Build CLI arguments ─────────────────────────────────────────────────
-function buildCliArgs(cliModel, sessionInfo) {
-  const args = ["-p", "--model", cliModel, "--output-format", "text"];
-
-  // Session handling
-  if (sessionInfo?.resume) {
-    args.push("--resume", sessionInfo.uuid);
-  } else if (sessionInfo?.uuid) {
-    args.push("--session-id", sessionInfo.uuid);
-  } else {
-    args.push("--no-session-persistence");
-  }
-
-  // Permissions
-  if (SKIP_PERMISSIONS) {
-    args.push("--dangerously-skip-permissions");
-  } else if (ALLOWED_TOOLS.length > 0) {
-    args.push("--allowedTools", ...ALLOWED_TOOLS);
-  }
-
-  // System prompt
-  if (SYSTEM_PROMPT) {
-    args.push("--append-system-prompt", SYSTEM_PROMPT);
-  }
-
-  // MCP config
-  if (MCP_CONFIG) {
-    args.push("--mcp-config", MCP_CONFIG);
-  }
-
-  return args;
-}
-
-// ── Format messages to prompt text ──────────────────────────────────────
-function messagesToPrompt(messages) {
-  return messages.map((m) => {
-    const text = typeof m.content === "string" ? m.content : JSON.stringify(m.content);
-    if (m.role === "system") return `[System] ${text}`;
-    if (m.role === "assistant") return `[Assistant] ${text}`;
-    return text;
-  }).join("\n\n");
-}
-
-// ── Call claude CLI ─────────────────────────────────────────────────────
-// On-demand spawning: each request spawns a fresh `claude -p` process.
-// No pool = no crash loops, no stale workers, no degraded states.
-// Stdin is written immediately so there's no 3s stdin timeout issue.
-function callClaude(model, messages, conversationId) {
-  return new Promise((resolve, reject) => {
-    if (stats.activeRequests >= MAX_CONCURRENT) {
-      return reject(new Error(`concurrency limit reached (${stats.activeRequests}/${MAX_CONCURRENT})`));
-    }
-    stats.activeRequests++;
-    stats.totalRequests++;
-
-    const cliModel = MODEL_MAP[model] || model;
-    let sessionInfo = null;
-    let prompt;
-
-    // ── Session logic ──
-    if (conversationId && sessions.has(conversationId)) {
-      // Resume existing session: only send the latest user message
-      const session = sessions.get(conversationId);
-      session.lastUsed = Date.now();
-      sessionInfo = { uuid: session.uuid, resume: true };
-      stats.sessionHits++;
-
-      const lastUserMsg = [...messages].reverse().find((m) => m.role === "user");
-      prompt = lastUserMsg
-        ? (typeof lastUserMsg.content === "string" ? lastUserMsg.content : JSON.stringify(lastUserMsg.content))
-        : "";
-      session.messageCount = messages.length;
-
-      console.log(`[session] resume conv=${conversationId.slice(0, 12)}... uuid=${session.uuid.slice(0, 8)}... msgs=${messages.length} prompt_chars=${prompt.length}`);
-
-    } else if (conversationId) {
-      // New session: send all messages, persist session for future --resume
-      const uuid = randomUUID();
-      sessions.set(conversationId, { uuid, messageCount: messages.length, lastUsed: Date.now(), model: cliModel });
-      sessionInfo = { uuid, resume: false };
-      stats.sessionMisses++;
-      prompt = messagesToPrompt(messages);
-
-      console.log(`[session] new conv=${conversationId.slice(0, 12)}... uuid=${uuid.slice(0, 8)}... msgs=${messages.length}`);
-
-    } else {
-      // One-off request, no session
-      stats.oneOffRequests++;
-      prompt = messagesToPrompt(messages);
-    }
-
-    const cliArgs = buildCliArgs(cliModel, sessionInfo);
-
-    const env = { ...process.env };
-    delete env.CLAUDECODE;
-    delete env.ANTHROPIC_API_KEY;
-    delete env.ANTHROPIC_BASE_URL;
-    delete env.ANTHROPIC_AUTH_TOKEN;
-
-    const proc = spawn(CLAUDE, cliArgs, { env, stdio: ["pipe", "pipe", "pipe"] });
-
-    let stdout = "";
-    let stderr = "";
-    const t0 = Date.now();
-    let settled = false;
-    let gotFirstByte = false;
-
-    function settle(err, result) {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      clearTimeout(firstByteTimer);
-      stats.activeRequests--;
-
-      if (err) {
-        trackError(err.message || String(err));
-
-        // If session resume failed, remove session so next request starts fresh
-        if (sessionInfo?.resume && conversationId) {
-          console.warn(`[session] resume failed for ${conversationId.slice(0, 12)}..., removing stale session`);
-          sessions.delete(conversationId);
-        }
-
-        reject(err);
-      } else {
-        resolve(result);
-      }
-    }
-
-    proc.stdout.on("data", (d) => {
-      if (!gotFirstByte) {
-        gotFirstByte = true;
-        clearTimeout(firstByteTimer);
-        console.log(`[claude] first-byte model=${cliModel} elapsed=${Date.now() - t0}ms`);
-      }
-      stdout += d;
-    });
-    proc.stderr.on("data", (d) => (stderr += d));
-
-    proc.on("close", (code) => {
-      const elapsed = Date.now() - t0;
-      if (code !== 0) {
-        console.error(`[claude] exit=${code} model=${cliModel} elapsed=${elapsed}ms stderr=${stderr.slice(0, 500)}`);
-        settle(new Error(stderr.slice(0, 300) || stdout.slice(0, 300) || `claude exit ${code}`));
-      } else {
-        console.log(`[claude] ok model=${cliModel} chars=${stdout.length} elapsed=${elapsed}ms session=${conversationId ? conversationId.slice(0, 12) + "..." : "none"}`);
-        settle(null, stdout.trim());
-      }
-    });
-
-    proc.on("error", (err) => {
-      console.error(`[claude] spawn error: ${err.message}`);
-      settle(err);
-    });
-
-    // Write prompt to stdin immediately — no idle timeout issue
-    proc.stdin.write(prompt);
-    proc.stdin.end();
-
-    console.log(`[claude] spawned model=${cliModel} prompt_chars=${prompt.length} session=${conversationId ? conversationId.slice(0, 12) + "..." : "none"}`);
-
-    // First-byte timeout: abort early if Claude CLI produces no output
-    const firstByteTimer = setTimeout(() => {
-      if (!gotFirstByte) {
-        stats.timeouts++;
-        console.error(`[claude] first-byte timeout after ${FIRST_BYTE_TIMEOUT}ms model=${cliModel} — aborting`);
-        proc.kill("SIGTERM");
-        setTimeout(() => { try { proc.kill("SIGKILL"); } catch {} }, 5000);
-        settle(new Error(`first-byte timeout after ${FIRST_BYTE_TIMEOUT}ms`));
-      }
-    }, FIRST_BYTE_TIMEOUT);
-
-    // Overall request timeout with graceful kill
-    const timer = setTimeout(() => {
-      stats.timeouts++;
-      console.error(`[claude] timeout after ${TIMEOUT}ms model=${cliModel}`);
-      proc.kill("SIGTERM");
-      setTimeout(() => { try { proc.kill("SIGKILL"); } catch {} }, 5000);
-      settle(new Error(`timeout after ${TIMEOUT}ms`));
-    }, TIMEOUT);
-  });
-}
-
-// ── Response helpers ────────────────────────────────────────────────────
-function jsonResponse(res, status, data) {
-  if (res.headersSent || res.writableEnded || res.destroyed) return;
-  res.writeHead(status, { "Content-Type": "application/json" });
-  res.end(JSON.stringify(data));
-}
-
-function sendSSE(res, data) {
-  res.write(`data: ${JSON.stringify(data)}\n\n`);
-}
-
-function streamResponse(res, id, model, content) {
-  if (res.headersSent || res.writableEnded || res.destroyed) return;
-  res.writeHead(200, {
-    "Content-Type": "text/event-stream",
-    "Cache-Control": "no-cache",
-    "Connection": "keep-alive",
-  });
-  const created = Math.floor(Date.now() / 1000);
-  sendSSE(res, {
-    id, object: "chat.completion.chunk", created, model,
-    choices: [{ index: 0, delta: { role: "assistant" }, finish_reason: null }],
-  });
-  for (let i = 0; i < content.length; i += 500) {
-    sendSSE(res, {
-      id, object: "chat.completion.chunk", created, model,
-      choices: [{ index: 0, delta: { content: content.slice(i, i + 500) }, finish_reason: null }],
-    });
-  }
-  sendSSE(res, {
-    id, object: "chat.completion.chunk", created, model,
-    choices: [{ index: 0, delta: {}, finish_reason: "stop" }],
-  });
-  res.write("data: [DONE]\n\n");
-  res.end();
-}
-
-function completionResponse(res, id, model, content) {
-  jsonResponse(res, 200, {
-    id, object: "chat.completion",
-    created: Math.floor(Date.now() / 1000),
-    model,
-    choices: [{ index: 0, message: { role: "assistant", content }, finish_reason: "stop" }],
-    usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
-  });
-}
-
-// ── Handle chat completions ─────────────────────────────────────────────
-async function handleChatCompletions(req, res) {
-  let body = "";
-  for await (const chunk of req) body += chunk;
-
-  let parsed;
-  try { parsed = JSON.parse(body); } catch { return jsonResponse(res, 400, { error: "Invalid JSON" }); }
-
-  const messages = parsed.messages || parsed.input || [{ role: "user", content: parsed.prompt || "" }];
-  const model = parsed.model || "claude-sonnet-4-6";
-  const stream = parsed.stream;
-
-  // Session ID: from request body, header, or null (one-off)
-  const conversationId = parsed.session_id || parsed.conversation_id || req.headers["x-session-id"] || req.headers["x-conversation-id"] || null;
-
-  if (!messages?.length) return jsonResponse(res, 400, { error: "messages required" });
-
-  try {
-    const content = await callClaude(model, messages, conversationId);
-    const id = `chatcmpl-${randomUUID()}`;
-
-    if (stream) {
-      streamResponse(res, id, model, content);
-    } else {
-      completionResponse(res, id, model, content);
-    }
-  } catch (err) {
-    console.error(`[proxy] error: ${err.message}`);
-    if (res.headersSent || res.writableEnded || res.destroyed) {
-      try { res.end(); } catch {}
-      return;
-    }
-    jsonResponse(res, 500, { error: { message: err.message, type: "proxy_error" } });
-  }
-}
-
-// ── HTTP server ─────────────────────────────────────────────────────────
-const server = createServer(async (req, res) => {
-  res.setHeader("Access-Control-Allow-Origin", "*");
-  res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
-  res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, X-Session-Id, X-Conversation-Id");
-  if (req.method === "OPTIONS") { res.writeHead(204); res.end(); return; }
-
-  // Bearer token auth (skip for /health and when PROXY_API_KEY is not set)
-  if (PROXY_API_KEY && req.url !== "/health") {
-    const auth = req.headers["authorization"] || "";
-    const token = auth.startsWith("Bearer ") ? auth.slice(7) : "";
-    if (token !== PROXY_API_KEY) {
-      return jsonResponse(res, 401, { error: { message: "Unauthorized: invalid or missing Bearer token", type: "auth_error" } });
-    }
-  }
-
-  // GET /v1/models
-  if (req.url === "/v1/models" && req.method === "GET") {
-    return jsonResponse(res, 200, {
-      object: "list",
-      data: MODELS.map((m) => ({
-        id: m.id, object: "model", owned_by: "anthropic",
-        created: Math.floor(Date.now() / 1000),
-      })),
-    });
-  }
-
-  // POST /v1/chat/completions
-  if (req.url === "/v1/chat/completions" && req.method === "POST") {
-    return handleChatCompletions(req, res);
-  }
-
-  // GET /health — comprehensive diagnostics
-  if (req.url === "/health") {
-    let binaryOk = false;
-    try { accessSync(CLAUDE, constants.X_OK); binaryOk = true; } catch {}
-
-    const uptimeMs = Date.now() - START_TIME;
-    const sessionList = [];
-    for (const [id, s] of sessions) {
-      sessionList.push({
-        id: id.slice(0, 12) + "...",
-        model: s.model,
-        messages: s.messageCount,
-        idleMs: Date.now() - s.lastUsed,
-      });
-    }
-
-    return jsonResponse(res, 200, {
-      status: binaryOk && authStatus.ok !== false ? "ok" : "degraded",
-      version: VERSION,
-      architecture: "on-demand (v2)",
-      uptime: uptimeMs,
-      uptimeHuman: `${Math.floor(uptimeMs / 3600000)}h ${Math.floor((uptimeMs % 3600000) / 60000)}m`,
-      claudeBinary: CLAUDE,
-      claudeBinaryOk: binaryOk,
-      auth: authStatus,
-      config: {
-        timeout: TIMEOUT,
-        firstByteTimeout: FIRST_BYTE_TIMEOUT,
-        maxConcurrent: MAX_CONCURRENT,
-        sessionTTL: SESSION_TTL,
-        allowedTools: SKIP_PERMISSIONS ? "all (skip-permissions)" : ALLOWED_TOOLS,
-        systemPrompt: SYSTEM_PROMPT ? `${SYSTEM_PROMPT.slice(0, 50)}...` : "(none)",
-        mcpConfig: MCP_CONFIG || "(none)",
-      },
-      stats,
-      sessions: sessionList,
-      recentErrors: recentErrors.slice(-5),
-    });
-  }
-
-  // DELETE /sessions — clear all sessions
-  if (req.url === "/sessions" && req.method === "DELETE") {
-    const count = sessions.size;
-    sessions.clear();
-    return jsonResponse(res, 200, { cleared: count });
-  }
-
-  // GET /sessions — list active sessions
-  if (req.url === "/sessions" && req.method === "GET") {
-    const list = [];
-    for (const [id, s] of sessions) {
-      list.push({ id, uuid: s.uuid, model: s.model, messages: s.messageCount, lastUsed: new Date(s.lastUsed).toISOString() });
-    }
-    return jsonResponse(res, 200, { sessions: list });
-  }
-
-  // Catch-all POST
-  if (req.method === "POST") {
-    return handleChatCompletions(req, res);
-  }
-
-  jsonResponse(res, 404, { error: "Not found. Endpoints: GET /v1/models, POST /v1/chat/completions, GET /health, GET|DELETE /sessions" });
-});
-
-// ── Start ───────────────────────────────────────────────────────────────
-server.listen(PORT, "0.0.0.0", () => {
-  console.log(`openclaw-claude-proxy v${VERSION} listening on http://0.0.0.0:${PORT}`);
-  console.log(`Architecture: on-demand spawning (no pool)`);
-  console.log(`Models: ${MODELS.map((m) => m.id).join(", ")}`);
-  console.log(`Claude binary: ${CLAUDE}`);
-  console.log(`Timeout: ${TIMEOUT}ms (first-byte: ${FIRST_BYTE_TIMEOUT}ms) | Max concurrent: ${MAX_CONCURRENT}`);
-  console.log(`Tools: ${SKIP_PERMISSIONS ? "all (skip-permissions)" : ALLOWED_TOOLS.join(", ")}`);
-  console.log(`Sessions: TTL=${SESSION_TTL / 1000}s`);
-  if (SYSTEM_PROMPT) console.log(`System prompt: "${SYSTEM_PROMPT.slice(0, 80)}..."`);
-  if (MCP_CONFIG) console.log(`MCP config: ${MCP_CONFIG}`);
-  console.log(`Auth: ${PROXY_API_KEY ? "enabled (PROXY_API_KEY set)" : "disabled (no PROXY_API_KEY)"}`);
-  console.log(`---`);
-  console.log(`Coexistence: This proxy does NOT conflict with Claude Code interactive mode.`);
-  console.log(`  OCP uses: localhost:${PORT} (HTTP) → claude -p (per-request process)`);
-  console.log(`  CC uses:  MCP protocol (in-process) → persistent session`);
-  console.log(`  Both can run simultaneously on the same machine.`);
-});

package.json

@@ -1,14 +1,16 @@
 {
-  "name": "openclaw-claude-proxy",
-  "version": "2.2.0",
-  "description": "OpenAI-compatible proxy that routes requests through Claude CLI \u2014 use your Claude Pro/Max subscription as an OpenClaw model provider",
+  "name": "open-claude-proxy",
+  "version": "3.16.2",
+  "description": "OCP (Open Claude Proxy) — use your Claude Pro/Max subscription as an OpenAI-compatible API for any IDE. Works with Cline, OpenCode, Aider, Continue.dev, OpenClaw, and more.",
   "type": "module",
   "bin": {
-    "openclaw-claude-proxy": "./server.mjs"
+    "openclaw-claude-proxy": "./server.mjs",
+    "ocp": "./ocp"
   },
   "scripts": {
     "start": "node server.mjs",
-    "setup": "node setup.mjs"
+    "setup": "node setup.mjs",
+    "test": "node test-features.mjs"
   },
   "keywords": [
     "openclaw",
@@ -19,10 +21,10 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=18"
+    "node": ">=22.5"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/dtzp555-max/openclaw-claude-proxy"
+    "url": "https://github.com/dtzp555-max/ocp"
   }
 }

scripts/doctor.mjs

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+/**
+ * scripts/doctor.mjs — OCP health & upgrade-readiness check.
+ *
+ * Usage:
+ *   ocp doctor                  human-readable PASS/WARN/FAIL
+ *   ocp doctor --json           machine-readable JSON for AI agents + ocp update
+ *   ocp doctor --check oauth    fast path: only OAuth check
+ *
+ * Exit codes:
+ *   0  all PASS or WARN-only
+ *   1  any FAIL
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { execSync } from "node:child_process";
+
+const SCHEMA_VERSION = "1";
+
+function semverParts(v) {
+  const m = String(v).replace(/^v/, "").match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!m) return null;
+  return { major: +m[1], minor: +m[2], patch: +m[3] };
+}
+
+function semverCompare(a, b) {
+  const A = semverParts(a), B = semverParts(b);
+  if (!A || !B) return 0;
+  if (A.major !== B.major) return A.major - B.major;
+  if (A.minor !== B.minor) return A.minor - B.minor;
+  return A.patch - B.patch;
+}
+
+export async function runDoctor(opts = {}) {
+  const checks = [];
+  const push = (id, level, message, extra = {}) =>
+    checks.push({ id, level, message, ...extra });
+
+  // --- fast path: --check oauth ---
+  if (opts.checkOnly === "oauth") {
+    return runOauthOnly(opts, checks, push);
+  }
+
+  // --- version detection ---
+  const ocpDir = opts.ocpDir || join(homedir(), "ocp");
+  let currentVersion = opts.mockVersion;
+  if (!currentVersion) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(ocpDir, "package.json"), "utf8"));
+      currentVersion = `v${pkg.version}`;
+    } catch {
+      currentVersion = "unknown";
+    }
+  }
+  // Resolve latest from origin/main (cheap: `git show origin/main:package.json`).
+  // Falls back to current_version when network/git unavailable, so kind = noop instead
+  // of recommending a downgrade against a stale hardcoded value.
+  let latestVersion = opts.mockLatest;
+  if (!latestVersion) {
+    try {
+      const out = execSync(`git -C ${ocpDir} show origin/main:package.json 2>/dev/null`, { stdio: ["pipe", "pipe", "pipe"] }).toString();
+      const remotePkg = JSON.parse(out);
+      latestVersion = `v${remotePkg.version}`;
+    } catch {
+      latestVersion = currentVersion;
+    }
+  }
+  push("current_version", "PASS", `current=${currentVersion}`);
+
+  // --- from-version supported? ---
+  const fromSupported = !!semverParts(currentVersion) && semverCompare(currentVersion, "v3.4.0") >= 0;
+  push("from_version_supported", fromSupported ? "PASS" : "FAIL",
+       fromSupported ? "≥ v3.4.0" : `${currentVersion} < v3.4.0; in-place upgrade not supported`);
+
+  // --- service health check (mockable) ---
+  let healthOk = true, oauthOk = true;
+  if (!opts.skipNetwork) {
+    let health;
+    if (opts.mockHealth !== undefined) {
+      health = opts.mockHealth;
+    } else {
+      try {
+        const port = process.env.CLAUDE_PROXY_PORT || "3478";
+        const out = execSync(`curl -sf --max-time 3 http://127.0.0.1:${port}/health`, { stdio: ["pipe", "pipe", "pipe"] }).toString();
+        health = { status: 200, body: JSON.parse(out) };
+      } catch (e) {
+        health = { error: String(e.message || e) };
+      }
+    }
+    if (health.error || health.status !== 200) {
+      healthOk = false;
+      push("service_running", "FAIL", `service unreachable: ${health.error || `status ${health.status}`}`);
+    } else if (!health.body || typeof health.body !== "object") {
+      healthOk = false;
+      push("service_running", "FAIL", "service /health returned 200 but empty/non-JSON body");
+    } else {
+      push("service_running", "PASS", "service responding on /health");
+      const authOk = health.body?.auth?.ok;
+      if (!authOk) {
+        oauthOk = false;
+        push("oauth_ok", "FAIL", `auth.ok=false: ${health.body?.auth?.message || "unknown"}`);
+      } else {
+        push("oauth_ok", "PASS", "OAuth token valid");
+      }
+    }
+  }
+
+  // --- determine next_action.kind (priority: fresh_install > fix_service > fix_oauth > noop > update > upgrade) ---
+  let kind;
+  if (!fromSupported) {
+    kind = "fresh_install";
+  } else if (!opts.skipNetwork && !healthOk) {
+    kind = "fix_service";
+  } else if (!opts.skipNetwork && !oauthOk) {
+    kind = "fix_oauth";
+  } else {
+    const cur = semverParts(currentVersion), lat = semverParts(latestVersion);
+    if (!cur) {
+      kind = "fresh_install";
+    } else if (semverCompare(currentVersion, latestVersion) === 0) {
+      kind = "noop";
+    } else if (lat && cur.major === lat.major && cur.minor === lat.minor) {
+      kind = "update";
+    } else {
+      kind = "upgrade";
+    }
+  }
+
+  // --- next_action shape ---
+  let next_action;
+  if (kind === "fresh_install") {
+    next_action = {
+      kind,
+      human_required: ["claude auth login (only if OAuth becomes invalid after reinstall)"],
+      ai_executable: [
+        `launchctl bootout gui/$(id -u)/ai.openclaw.proxy 2>/dev/null || true`,
+        `launchctl bootout gui/$(id -u)/dev.ocp.proxy 2>/dev/null || true`,
+        `mv ${join(homedir(), ".ocp")} ${join(homedir(), ".ocp.backup-")}$(date +%s) 2>/dev/null || true`,
+        `rm -rf ${ocpDir}`,
+        `git clone https://github.com/dtzp555-max/ocp ${ocpDir}`,
+        `cd ${ocpDir} && npm install --no-audit --no-fund && node setup.mjs`,
+        `${ocpDir}/ocp doctor`
+      ],
+      verify: "ocp doctor expects PASS on all checks"
+    };
+  } else if (kind === "noop") {
+    next_action = { kind, human_required: [], ai_executable: [], verify: "already at latest" };
+  } else if (kind === "fix_oauth") {
+    next_action = {
+      kind,
+      human_required: [],
+      ai_executable: [
+        `cd "$(npm root -g)/@anthropic-ai/claude-code" && node install.cjs`,
+        `launchctl bootout gui/$(id -u)/dev.ocp.proxy 2>/dev/null || true`,
+        `launchctl bootstrap gui/$(id -u) ${join(homedir(), "Library", "LaunchAgents", "dev.ocp.proxy.plist")}`,
+        `${ocpDir}/ocp doctor`
+      ],
+      verify: "ocp doctor expects oauth_ok=PASS",
+      reference: "~/.cc-rules/memory/learnings/ocp_claude_native_binary_postinstall.md"
+    };
+  } else if (kind === "fix_service") {
+    next_action = {
+      kind,
+      human_required: [],
+      ai_executable: [
+        `launchctl bootout gui/$(id -u)/dev.ocp.proxy 2>/dev/null || true`,
+        `launchctl bootstrap gui/$(id -u) ${join(homedir(), "Library", "LaunchAgents", "dev.ocp.proxy.plist")}`,
+        `${ocpDir}/ocp doctor`
+      ],
+      verify: "ocp doctor expects service_running=PASS"
+    };
+  } else {
+    next_action = {
+      kind,
+      human_required: [],
+      ai_executable: [`${ocpDir}/ocp update --yes`],
+      verify: "ocp doctor expects PASS on all checks"
+    };
+  }
+
+  const fail_count = checks.filter(c => c.level === "FAIL").length;
+  const warn_count = checks.filter(c => c.level === "WARN").length;
+  return {
+    schema_version: SCHEMA_VERSION,
+    timestamp: new Date().toISOString(),
+    ready_to_upgrade: fail_count === 0,
+    current_version: currentVersion,
+    latest_version: latestVersion,
+    from_version_supported: fromSupported,
+    fail_count,
+    warn_count,
+    checks,
+    next_action
+  };
+}
+
+function runOauthOnly(opts, checks, push) {
+  let healthOk = true, oauthOk = true;
+  let health;
+  if (opts.mockHealth !== undefined) {
+    health = opts.mockHealth;
+  } else {
+    try {
+      const port = process.env.CLAUDE_PROXY_PORT || "3478";
+      const out = execSync(`curl -sf --max-time 3 http://127.0.0.1:${port}/health`, { stdio: ["pipe", "pipe", "pipe"] }).toString();
+      health = { status: 200, body: JSON.parse(out) };
+    } catch (e) {
+      health = { error: String(e.message || e) };
+    }
+  }
+
+  if (health.error || health.status !== 200) {
+    healthOk = false;
+    push("oauth_ok", "FAIL", `service unreachable: ${health.error || `status ${health.status}`}`);
+  } else if (!health.body || typeof health.body !== "object") {
+    healthOk = false;
+    push("oauth_ok", "FAIL", "service /health returned 200 but empty/non-JSON body");
+  } else if (!health.body?.auth?.ok) {
+    oauthOk = false;
+    push("oauth_ok", "FAIL", `auth.ok=false: ${health.body?.auth?.message || "unknown"}`);
+  } else {
+    push("oauth_ok", "PASS", "OAuth token valid");
+  }
+
+  const kind = !healthOk ? "fix_service" : !oauthOk ? "fix_oauth" : "noop";
+
+  let next_action;
+  const ocpDir = opts.ocpDir || join(homedir(), "ocp");
+  if (kind === "noop") {
+    next_action = { kind, human_required: [], ai_executable: [], verify: "OAuth healthy" };
+  } else if (kind === "fix_oauth") {
+    next_action = {
+      kind,
+      human_required: [],
+      ai_executable: [
+        `cd "$(npm root -g)/@anthropic-ai/claude-code" && node install.cjs`,
+        `launchctl bootout gui/$(id -u)/dev.ocp.proxy 2>/dev/null || true`,
+        `launchctl bootstrap gui/$(id -u) ${join(homedir(), "Library", "LaunchAgents", "dev.ocp.proxy.plist")}`,
+        `${ocpDir}/ocp doctor --check oauth`
+      ],
+      verify: "ocp doctor --check oauth expects PASS",
+      reference: "~/.cc-rules/memory/learnings/ocp_claude_native_binary_postinstall.md"
+    };
+  } else {
+    next_action = {
+      kind,
+      human_required: [],
+      ai_executable: [
+        `launchctl bootout gui/$(id -u)/dev.ocp.proxy 2>/dev/null || true`,
+        `launchctl bootstrap gui/$(id -u) ${join(homedir(), "Library", "LaunchAgents", "dev.ocp.proxy.plist")}`,
+        `${ocpDir}/ocp doctor --check oauth`
+      ],
+      verify: "ocp doctor --check oauth expects service_running=PASS"
+    };
+  }
+
+  const fail_count = checks.filter(c => c.level === "FAIL").length;
+  // "skipped" = --check oauth fast path intentionally omits version detection.
+  // AI agents should NOT semver-compare against current_version/latest_version when
+  // either equals "skipped"; the full path provides those fields when needed.
+  return {
+    schema_version: SCHEMA_VERSION,
+    timestamp: new Date().toISOString(),
+    ready_to_upgrade: fail_count === 0,
+    current_version: opts.mockVersion || "skipped",
+    latest_version: opts.mockLatest || "skipped",
+    from_version_supported: true,
+    fail_count,
+    warn_count: 0,
+    checks,
+    next_action
+  };
+}
+
+// CLI entrypoint — use fileURLToPath + realpath to handle symlinked install paths
+// (e.g. /tmp/ → /private/tmp/ on macOS would otherwise miss the guard).
+import { fileURLToPath } from "node:url";
+import { realpathSync } from "node:fs";
+function _isMain() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+  } catch { return false; }
+}
+if (_isMain()) {
+  const wantJson = process.argv.includes("--json");
+  const checkIdx = process.argv.indexOf("--check");
+  const checkOnly = checkIdx !== -1 ? process.argv[checkIdx + 1] : undefined;
+  const result = await runDoctor({ checkOnly });
+  if (wantJson) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`OCP doctor — ${result.current_version} → ${result.latest_version}`);
+    for (const c of result.checks) console.log(`  [${c.level}] ${c.id}: ${c.message}`);
+    console.log(`\nSummary: ${result.fail_count} FAIL, ${result.warn_count} WARN`);
+    console.log(`Next action: ${result.next_action.kind}`);
+  }
+  process.exit(result.fail_count === 0 ? 0 : 1);
+}

scripts/heartbeat-field-check.sh

@@ -0,0 +1,132 @@
+#!/bin/bash
+# One-shot field-evidence gatherer for OCP v3.12.0 SSE heartbeat.
+# Scheduled by ~/Library/LaunchAgents/dev.ocp.heartbeat-check.plist to fire
+# once at 2026-05-02 09:00 Australia/Brisbane. Gathers evidence from local
+# OCP logs + GitHub issue #47 + repo issue search, posts a summary comment
+# on #47, and exits. Does NOT open PRs or change code — the maintainer
+# decides after reading the summary.
+#
+# Dry-run: ./heartbeat-field-check.sh --dry-run   (prints summary, skips post)
+
+set -euo pipefail
+
+REPO="dtzp555-max/ocp"
+SHIP_DATE="2026-04-25"
+# Baseline captured at script-install time so internal testing entries from
+# Phase 3 verification (~5 entries from 2026-04-25T00:00–00:48Z) don't get
+# counted as field evidence. Any heartbeat_active log entry with ts >= this
+# timestamp is treated as a real opt-in.
+BASELINE_TS="2026-04-25T01:00:00Z"
+PROXY_LOG="$HOME/ocp/logs/proxy.log"
+OUT_DIR="$HOME/ocp/logs"
+SELF_LOG="$OUT_DIR/heartbeat-field-check-$(date +%Y-%m-%d).log"
+DRY_RUN=0
+[ "${1:-}" = "--dry-run" ] && DRY_RUN=1
+
+mkdir -p "$OUT_DIR"
+
+exec > >(tee -a "$SELF_LOG") 2>&1
+
+echo "=== heartbeat field-evidence check: $(date -u +%Y-%m-%dT%H:%M:%SZ) (dry_run=$DRY_RUN) ==="
+
+# ── signal 1: local proxy log ─────────────────────────────────────────────
+if [ -r "$PROXY_LOG" ]; then
+  # Only count entries with ts >= BASELINE_TS (string sort works on RFC3339)
+  HEARTBEAT_COUNT=$(grep '"event":"heartbeat_active"' "$PROXY_LOG" 2>/dev/null \
+    | awk -v base="$BASELINE_TS" '
+        match($0, /"ts":"[^"]+"/) {
+          ts = substr($0, RSTART+6, RLENGTH-7);
+          if (ts >= base) c++
+        }
+        END { print c+0 }')
+else
+  HEARTBEAT_COUNT=0
+fi
+echo "signal 1 — heartbeat_active log entries since $BASELINE_TS: $HEARTBEAT_COUNT"
+
+# ── signal 2: comments on #47 since ship ──────────────────────────────────
+NEW_47_JSON="/tmp/ocp-47-new-comments-$$.json"
+gh issue view 47 --repo "$REPO" --json comments \
+  --jq '[.comments[] | select(.createdAt >= "'"$SHIP_DATE"'T00:00:00Z")]' \
+  > "$NEW_47_JSON" 2>/dev/null || echo "[]" > "$NEW_47_JSON"
+NEW_COMMENTS=$(jq 'length' "$NEW_47_JSON")
+echo "signal 2 — new comments on #47 since $SHIP_DATE: $NEW_COMMENTS"
+
+# Build a compact, human-readable excerpt for the summary body
+NEW_47_EXCERPT=""
+if [ "$NEW_COMMENTS" -gt 0 ]; then
+  NEW_47_EXCERPT=$(jq -r '.[] | "- **@\(.author.login)** (\(.createdAt)): " + (.body | gsub("\r"; "") | split("\n")[0])[:180]' "$NEW_47_JSON")
+fi
+
+# ── signal 3: other heartbeat-related issues since ship ──────────────────
+OTHER_ISSUES_JSON="/tmp/ocp-heartbeat-issues-$$.json"
+gh search issues "repo:$REPO heartbeat" --json number,title,state,createdAt --limit 30 \
+  --jq '[.[] | select(.createdAt >= "'"$SHIP_DATE"'T00:00:00Z" and .number != 47 and .number != 48)]' \
+  > "$OTHER_ISSUES_JSON" 2>/dev/null || echo "[]" > "$OTHER_ISSUES_JSON"
+OTHER_ISSUES=$(jq 'length' "$OTHER_ISSUES_JSON")
+echo "signal 3 — other heartbeat-related issues since ship: $OTHER_ISSUES"
+
+OTHER_ISSUES_EXCERPT=""
+if [ "$OTHER_ISSUES" -gt 0 ]; then
+  OTHER_ISSUES_EXCERPT=$(jq -r '.[] | "- #\(.number) [\(.state)] \(.title)"' "$OTHER_ISSUES_JSON")
+fi
+
+# ── compose summary ──────────────────────────────────────────────────────
+BODY_FILE="/tmp/ocp-47-summary-$$.md"
+{
+  echo "### Automated 7-day field-evidence check (v3.12.0)"
+  echo
+  echo "_Triggered by a local launchd scheduled task on the maintainer's rig at $(date -u +%Y-%m-%dT%H:%M:%SZ)._"
+  echo
+  echo "| Signal | Count |"
+  echo "|---|---|"
+  echo "| \`heartbeat_active\` log entries on prod rig (since baseline $BASELINE_TS) | $HEARTBEAT_COUNT |"
+  echo "| New comments on #47 since $SHIP_DATE | $NEW_COMMENTS |"
+  echo "| Other heartbeat-related issues filed since $SHIP_DATE | $OTHER_ISSUES |"
+  echo
+  if [ -n "$NEW_47_EXCERPT" ]; then
+    echo "**New #47 comments (first line each):**"
+    echo
+    echo "$NEW_47_EXCERPT"
+    echo
+  fi
+  if [ -n "$OTHER_ISSUES_EXCERPT" ]; then
+    echo "**Other heartbeat-related issues:**"
+    echo
+    echo "$OTHER_ISSUES_EXCERPT"
+    echo
+  fi
+  echo "**Decision guidance for maintainer (manual):**"
+  echo
+  echo "- If any of the above indicate a **crash report** on \`: keepalive\` comment frames → leave default at \`0\` and file a \`CLAUDE_HEARTBEAT_FORMAT=empty-delta\` follow-up issue (spec \`§D2\` fallback plan)."
+  echo "- If there is at least one **opt-in confirmation** (a user reports \`CLAUDE_HEARTBEAT_INTERVAL\` fixed their timeout issue) and no crash reports → consider opening a PR for v3.13.0 flipping the default to \`30000\`, following the same ALIGNMENT + independent-reviewer + release-kit discipline as PR #49."
+  echo "- If all three signals are zero → extend the soak window or close this follow-up as \"no field evidence.\""
+  echo
+  echo "This bot does not open PRs or change code. The maintainer reviews and acts."
+} > "$BODY_FILE"
+
+echo "--- summary preview ---"
+cat "$BODY_FILE"
+echo "--- end preview ---"
+
+# ── post (unless dry-run) ────────────────────────────────────────────────
+if [ "$DRY_RUN" -eq 1 ]; then
+  echo "DRY RUN — skipping gh issue comment"
+else
+  gh issue comment 47 --repo "$REPO" --body-file "$BODY_FILE" && echo "comment posted on #47"
+fi
+
+# ── cleanup + self-disable so the plist doesn't linger loaded forever ────
+rm -f "$NEW_47_JSON" "$OTHER_ISSUES_JSON" "$BODY_FILE"
+
+if [ "$DRY_RUN" -eq 0 ]; then
+  # Unload + remove the plist so this never fires again
+  PLIST="$HOME/Library/LaunchAgents/dev.ocp.heartbeat-check.plist"
+  if [ -f "$PLIST" ]; then
+    launchctl bootout "gui/$(id -u)" "$PLIST" 2>/dev/null || launchctl unload "$PLIST" 2>/dev/null || true
+    rm -f "$PLIST"
+    echo "self-disabled: removed $PLIST"
+  fi
+fi
+
+echo "=== done ==="

scripts/lib/plist-merge.mjs

@@ -0,0 +1,86 @@
+// scripts/lib/plist-merge.mjs
+//
+// Preserves user-customised env vars when setup.mjs rewrites the unit file.
+//
+// Rule:
+//   - keys present in NEW template → template value wins (template is source of truth)
+//   - keys ONLY in EXISTING (not in template) → preserved verbatim
+//
+// No new dependencies — regex-based, plist <key>X</key><string>Y</string> shape
+// is stable enough for our hand-written templates in setup.mjs.
+
+const PLIST_KV_RE = /<key>([^<]+)<\/key>\s*<string>([^<]*)<\/string>/g;
+
+export function parsePlistEnv(plistContent) {
+  if (!plistContent) return {};
+  if (Buffer.isBuffer(plistContent)) plistContent = plistContent.toString("utf8");
+  // Restrict to the EnvironmentVariables dict to avoid catching Label, etc.
+  const envBlock = plistContent.match(/<key>EnvironmentVariables<\/key>\s*<dict>([\s\S]*?)<\/dict>/);
+  if (!envBlock) return {};
+  const out = {};
+  let m;
+  PLIST_KV_RE.lastIndex = 0;
+  while ((m = PLIST_KV_RE.exec(envBlock[1])) !== null) {
+    out[m[1]] = m[2];
+  }
+  return out;
+}
+
+export function mergePlistEnv(existing, template) {
+  if (!existing) return template;
+  const existingEnv = parsePlistEnv(existing);
+  const templateEnv = parsePlistEnv(template);
+  const KNOWN = new Set(Object.keys(templateEnv));
+
+  const preserved = {};
+  for (const [k, v] of Object.entries(existingEnv)) {
+    if (!KNOWN.has(k)) preserved[k] = v;
+  }
+  if (Object.keys(preserved).length === 0) return template;
+
+  const lines = Object.entries(preserved)
+    .map(([k, v]) => `    <key>${k}</key>\n    <string>${v}</string>`)
+    .join("\n");
+
+  // Inject before the closing </dict> of EnvironmentVariables
+  return template.replace(
+    /(<key>EnvironmentVariables<\/key>\s*<dict>[\s\S]*?)(\n\s*<\/dict>)/,
+    `$1\n${lines}$2`
+  );
+}
+
+const SYSTEMD_KV_RE = /^Environment=([^=]+)=(.*)$/gm;
+
+export function parseSystemdEnv(serviceContent) {
+  if (!serviceContent) return {};
+  if (Buffer.isBuffer(serviceContent)) serviceContent = serviceContent.toString("utf8");
+  const out = {};
+  let m;
+  SYSTEMD_KV_RE.lastIndex = 0;
+  while ((m = SYSTEMD_KV_RE.exec(serviceContent)) !== null) {
+    out[m[1]] = m[2];
+  }
+  return out;
+}
+
+export function mergeSystemdEnv(existing, template) {
+  if (!existing) return template;
+  const existingEnv = parseSystemdEnv(existing);
+  const templateEnv = parseSystemdEnv(template);
+  const KNOWN = new Set(Object.keys(templateEnv));
+
+  const preservedLines = Object.entries(existingEnv)
+    .filter(([k]) => !KNOWN.has(k))
+    .map(([k, v]) => `Environment=${k}=${v}`);
+  if (preservedLines.length === 0) return template;
+
+  // Guard: if template has no Environment= anchor, cannot inject — return template as-is.
+  // (In practice the OCP systemd template always has Environment= lines.)
+  if (!/^Environment=/m.test(template)) return template;
+
+  // Inject after the last existing Environment= line in the template
+  return template.replace(
+    /(^Environment=[^\n]+\n)((?!Environment=).*$)/ms,
+    `$1${preservedLines.join("\n")}\n$2`
+  );
+}

scripts/lib/snapshot.mjs

@@ -0,0 +1,115 @@
+import { mkdirSync, writeFileSync, readFileSync, copyFileSync, existsSync, readdirSync, statSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+export function writeSnapshot({ homeDir, fromCommit, fromVersion, toVersion, extraFiles = [] }) {
+  const ts = new Date().toISOString().replace(/\.\d+Z$/, "Z");
+  const root = join(homeDir, ".ocp", `upgrade-snapshot-${ts}`);
+  mkdirSync(root, { recursive: true });
+
+  // Standard manifest files
+  writeFileSync(join(root, "from-commit.txt"), fromCommit + "\n");
+  writeFileSync(join(root, "from-version.txt"), fromVersion + "\n");
+  writeFileSync(join(root, "to-version.txt"), toVersion + "\n");
+
+  // Optional captures (best-effort, never fatal)
+  const tryCopy = (src, dst) => {
+    try {
+      if (existsSync(src)) copyFileSync(src, dst);
+    } catch (err) {
+      console.error(`[snapshot] warn: could not copy ${src} (${err.code || err.message})`);
+    }
+  };
+  tryCopy(join(homeDir, "Library", "LaunchAgents", "dev.ocp.proxy.plist"), join(root, "plist"));
+  tryCopy(join(homeDir, ".config", "systemd", "user", "ocp-proxy.service"), join(root, "service"));
+  tryCopy(join(homeDir, ".ocp", "ocp.db"), join(root, "db.bak"));
+  tryCopy(join(homeDir, ".ocp", "admin-key"), join(root, "admin-key"));
+  tryCopy(join(homeDir, ".openclaw", "openclaw.json"), join(root, "openclaw.json"));
+
+  for (const { src, name } of extraFiles) tryCopy(src, join(root, name));
+
+  return root;
+}
+
+export function readSnapshot(snapshotPath) {
+  const read = (n) => {
+    try { return readFileSync(join(snapshotPath, n), "utf8").trim(); } catch { return null; }
+  };
+  return {
+    path: snapshotPath,
+    fromCommit: read("from-commit.txt"),
+    fromVersion: read("from-version.txt"),
+    toVersion: read("to-version.txt")
+  };
+}
+
+export function listSnapshots(homeDir) {
+  const root = join(homeDir, ".ocp");
+  if (!existsSync(root)) return [];
+  return readdirSync(root)
+    .filter(name => name.startsWith("upgrade-snapshot-"))
+    .map(name => ({ name, path: join(root, name), mtime: statSync(join(root, name)).mtimeMs }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Garbage-collect old upgrade snapshots.
+ *
+ * Retention rule (a snapshot is KEPT if any of these is true):
+ *   - It is among the last `keepCount` snapshots (sorted oldest→newest)
+ *   - Its timestamp is within `keepDays` of `now`
+ *   - It is the single most-recent snapshot (always-keep safety net)
+ *
+ * @param {string} homeDir - Root containing ~/.ocp/
+ * @param {object} opts
+ * @param {number} [opts.keepCount=5] - Minimum count to keep
+ * @param {number} [opts.keepDays=30] - Keep snapshots newer than N days
+ * @param {boolean} [opts.dryRun=false] - If true, report plan but don't delete
+ * @param {Date} [opts.now=new Date()] - Override clock for testing
+ * @returns {{kept: Array, removed: Array, dryRun: boolean}}
+ */
+export function gcSnapshots(homeDir, opts = {}) {
+  const keepCount = opts.keepCount ?? 5;
+  const keepDays = opts.keepDays ?? 30;
+  const dryRun = !!opts.dryRun;
+  const now = opts.now || new Date();
+
+  const all = listSnapshots(homeDir);  // sorted oldest→newest
+  if (all.length === 0) return { kept: [], removed: [], dryRun };
+  if (all.length === 1) return { kept: all, removed: [], dryRun };  // always keep most recent
+
+  const cutoffMs = now.getTime() - keepDays * 24 * 60 * 60 * 1000;
+  const lastN = new Set(all.slice(-keepCount).map(s => s.path));
+
+  const kept = [], removed = [];
+  for (let i = 0; i < all.length; i++) {
+    const s = all[i];
+    const isMostRecent = i === all.length - 1;
+    const isInLastN = lastN.has(s.path);
+    const isWithinDays = parseSnapshotTimestamp(s.name) >= cutoffMs;
+    if (isMostRecent || isInLastN || isWithinDays) {
+      kept.push(s);
+    } else {
+      removed.push(s);
+    }
+  }
+
+  if (!dryRun) {
+    for (const s of removed) {
+      try {
+        rmSync(s.path, { recursive: true, force: true });
+      } catch (err) {
+        console.error(`[snapshot] warn: could not remove ${s.path} (${err.code || err.message})`);
+      }
+    }
+  }
+
+  return { kept, removed, dryRun };
+}
+
+function parseSnapshotTimestamp(name) {
+  // upgrade-snapshot-2026-05-11T08:30:00Z → epoch ms
+  const m = name.match(/upgrade-snapshot-(.+)$/);
+  if (!m) return 0;
+  const t = Date.parse(m[1]);
+  return Number.isFinite(t) ? t : 0;
+}

scripts/sync-openclaw.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// Idempotently sync OCP's claude-local provider models into OpenClaw's registry.
+// Only touches:
+//   - config.models.providers["claude-local"].models
+//   - config.agents.defaults.models["claude-local/*"] keys
+// All other fields and providers are preserved.
+
+import { readFileSync, writeFileSync, existsSync, copyFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(__dirname, "..");
+const OPENCLAW_CONFIG = join(homedir(), ".openclaw", "openclaw.json");
+const PROVIDER_NAME = "claude-local";
+const QUIET = process.argv.includes("--quiet");
+
+function log(msg) { if (!QUIET) console.log(`  ✓ ${msg}`); }
+function warn(msg) { console.warn(`  ⚠ ${msg}`); }
+
+if (!existsSync(OPENCLAW_CONFIG)) {
+  log(`OpenClaw not installed at ${OPENCLAW_CONFIG} — skipping (this is fine for non-OpenClaw users)`);
+  process.exit(0);
+}
+
+const modelsConfig = JSON.parse(readFileSync(join(REPO_ROOT, "models.json"), "utf-8"));
+const desiredModels = modelsConfig.models.map(m => ({
+  id: m.id,
+  name: m.openclawName,
+  reasoning: m.reasoning,
+  input: ["text"],
+  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+  contextWindow: m.contextWindow,
+  maxTokens: m.maxTokens,
+}));
+const desiredAliases = Object.fromEntries(
+  modelsConfig.models.map(m => [`${PROVIDER_NAME}/${m.id}`, { alias: m.displayName }])
+);
+
+const config = JSON.parse(readFileSync(OPENCLAW_CONFIG, "utf-8"));
+
+// Compute diff before writing
+const existingModels = config?.models?.providers?.[PROVIDER_NAME]?.models ?? [];
+const existingIds = new Set(existingModels.map(m => m.id));
+const desiredIds = new Set(desiredModels.map(m => m.id));
+const added = [...desiredIds].filter(id => !existingIds.has(id));
+const removed = [...existingIds].filter(id => !desiredIds.has(id));
+
+if (added.length === 0 && removed.length === 0 && existingModels.length === desiredModels.length) {
+  // Check deep equality too in case names/maxTokens changed
+  const changed = desiredModels.some((d) => {
+    const e = existingModels.find(x => x.id === d.id);
+    return !e || e.name !== d.name || e.maxTokens !== d.maxTokens;
+  });
+  if (!changed) {
+    log("OpenClaw registry already in sync");
+    process.exit(0);
+  }
+}
+
+// Backup
+const backupPath = `${OPENCLAW_CONFIG}.bak.${Date.now()}`;
+copyFileSync(OPENCLAW_CONFIG, backupPath);
+log(`Backed up to ${backupPath}`);
+
+// Surgical patch: only touch claude-local provider and claude-local/* aliases
+if (!config.models) config.models = {};
+if (!config.models.providers) config.models.providers = {};
+if (!config.models.providers[PROVIDER_NAME]) {
+  // First-time registration
+  config.models.providers[PROVIDER_NAME] = {
+    baseUrl: "http://127.0.0.1:3456/v1",
+    api: "openai-completions",
+    authHeader: false,
+    models: desiredModels,
+  };
+} else {
+  // Update only the models array; leave baseUrl/api/authHeader untouched (user may have customized port)
+  config.models.providers[PROVIDER_NAME].models = desiredModels;
+}
+
+if (!config.agents) config.agents = {};
+if (!config.agents.defaults) config.agents.defaults = {};
+if (!config.agents.defaults.models) config.agents.defaults.models = {};
+
+// Remove stale claude-local/* aliases, then add desired ones
+for (const key of Object.keys(config.agents.defaults.models)) {
+  if (key.startsWith(`${PROVIDER_NAME}/`)) delete config.agents.defaults.models[key];
+}
+Object.assign(config.agents.defaults.models, desiredAliases);
+
+writeFileSync(OPENCLAW_CONFIG, JSON.stringify(config, null, 2) + "\n");
+
+if (added.length > 0) log(`Added: ${added.join(", ")}`);
+if (removed.length > 0) log(`Removed (no longer in models.json): ${removed.join(", ")}`);
+log(`OpenClaw registry synced: ${desiredModels.length} models registered`);

scripts/upgrade.mjs

@@ -0,0 +1,344 @@
+#!/usr/bin/env node
+/**
+ * scripts/upgrade.mjs — OCP unified upgrade dispatcher.
+ *
+ * Paths:
+ *   noop          current == latest, exit 0
+ *   light         same major.minor, patch bump only (existing fast path; delegated to bash)
+ *   full          cross-minor (snapshot + setup.mjs + post-flight)
+ *   fresh_install from-version < v3.4.0 (--yes required for non-interactive)
+ *   rollback      restore from snapshot
+ */
+import { runDoctor } from "./doctor.mjs";
+import { execSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { existsSync, copyFileSync } from "node:fs";
+import { writeSnapshot, listSnapshots, readSnapshot, gcSnapshots } from "./lib/snapshot.mjs";
+
+export async function runUpgrade(opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const yes = !!opts.yes;
+  // yes is reserved for Bundle 3 (fresh-install / rollback interactive gate); not used in upgrade-path here.
+  const plan = [];
+
+  // --- rollback path (no doctor needed; snapshot is authoritative) ---
+  if (opts.rollback) {
+    return await runRollback(opts);
+  }
+
+  // --- doctor pre-flight ---
+  const doctor = opts.mockDoctor || await runDoctor();
+  if (!doctor.ready_to_upgrade && doctor.next_action.kind !== "fresh_install") {
+    throw new Error(`doctor FAIL: ${doctor.next_action.kind} (run "ocp doctor" for details)`);
+  }
+
+  const kind = doctor.next_action.kind;
+  plan.push(`[doctor] from=${doctor.current_version} to=${doctor.latest_version} kind=${kind}`);
+
+  // --- noop ---
+  if (kind === "noop") {
+    plan.push(`[noop] already at latest (${doctor.latest_version})`);
+    return { path: "noop", executed: true, changed: false, plan };
+  }
+
+  // --- dry-run early exit ---
+  if (dryRun) {
+    plan.push(`[plan] would proceed with ${kind} path`);
+    if (kind === "upgrade") {
+      plan.push(`[plan] phase 1: snapshot to ~/.ocp/upgrade-snapshot-<ts>/`);
+      plan.push(`[plan] phase 2: git checkout ${doctor.latest_version} && npm install`);
+      plan.push(`[plan] phase 3: node setup.mjs`);
+      plan.push(`[plan] phase 4: launchctl bootout/bootstrap`);
+      plan.push(`[plan] phase 5: post-flight /health + /v1/models`);
+    } else if (kind === "update") {
+      plan.push(`[plan] light path: git pull + npm install + restart`);
+    } else if (kind === "fresh_install") {
+      plan.push(`[plan] fresh-install ai_executable[]:`);
+      for (const cmd of doctor.next_action.ai_executable) plan.push(`  - ${cmd}`);
+    }
+    return { path: kind, executed: false, plan };
+  }
+
+  // --- non-dry-run paths ---
+  if (kind === "update") {
+    return { path: "update", executed: true, changed: true, plan: [...plan, "[light] delegated to bash cmd_update existing logic"] };
+  }
+
+  if (kind === "upgrade") {
+    return await runFullUpgrade({ doctor, opts });
+  }
+
+  if (kind === "fresh_install") {
+    return await runFreshInstall({ doctor, opts });
+  }
+
+  throw new Error(`path ${kind} not yet implemented`);
+}
+
+async function runFullUpgrade({ doctor, opts }) {
+  const phases = [];
+  let snapshotPath = null;
+  const exec = (cmd, label) => {
+    if (opts.mockExec) {
+      phases.push({ name: label, cmd, status: "skipped-mock" });
+      return "";
+    }
+    try {
+      const out = execSync(cmd, { stdio: ["pipe", "pipe", "pipe"] }).toString();
+      phases.push({ name: label, cmd, status: "ok" });
+      return out;
+    } catch (err) {
+      const detail = err.stderr?.toString().trim();
+      phases.push({ name: label, cmd, status: "fail", stderr: detail });
+      throw Object.assign(
+        new Error(`phase ${label} failed: ${detail || err.message}`),
+        { phases, cmd }
+      );
+    }
+  };
+  const ocpDir = opts.ocpDir || join(homedir(), "ocp");
+
+  try {
+    // phase 1: pre-flight (doctor already passed; just record)
+    phases.push({ name: "pre-flight", status: "ok", note: `kind=upgrade from=${doctor.current_version} to=${doctor.latest_version}` });
+
+    // phase 2: snapshot
+    const fromCommit = opts.mockExec
+      ? "mock-commit"
+      : execSync(`git -C ${ocpDir} rev-parse HEAD`).toString().trim();
+    snapshotPath = opts.mockExec
+      ? "/tmp/mock-snapshot"
+      : writeSnapshot({ homeDir: homedir(), fromCommit, fromVersion: doctor.current_version, toVersion: doctor.latest_version });
+    phases.push({ name: "snapshot", path: snapshotPath, status: "ok" });
+
+    // phase 3: fetch + install
+    exec(`git -C ${ocpDir} fetch --tags --quiet`, "fetch+install");
+    exec(`git -C ${ocpDir} checkout ${doctor.latest_version}`, "fetch+install");
+    exec(`npm --prefix ${ocpDir} install --no-audit --no-fund`, "fetch+install");
+
+    // phase 4: reconfigure
+    exec(`node ${ocpDir}/setup.mjs`, "reconfigure");
+
+    // phase 5: restart (heads-up note printed before invoking)
+    if (!opts.mockExec) {
+      console.error(`[heads-up] restarting OCP service in 3s — expect ~5–10s blip on requests in flight.`);
+      await new Promise(r => setTimeout(r, 3000));
+    }
+    if (process.platform === "darwin") {
+      exec(`launchctl bootout gui/$(id -u)/dev.ocp.proxy 2>/dev/null || true`, "restart");
+      exec(`launchctl bootstrap gui/$(id -u) ${join(homedir(), "Library", "LaunchAgents", "dev.ocp.proxy.plist")}`, "restart");
+    } else {
+      exec(`systemctl --user restart ocp-proxy.service`, "restart");
+    }
+
+    // phase 6: post-flight (10s budget; skipped under mockExec)
+    if (!opts.mockExec) {
+      const port = process.env.CLAUDE_PROXY_PORT || "3478";
+      let ok = false;
+      for (let i = 0; i < 10; i++) {
+        try {
+          const out = execSync(`curl -sf --max-time 2 http://127.0.0.1:${port}/health`).toString();
+          const body = JSON.parse(out);
+          if (body.auth?.ok === true) { ok = true; break; }
+        } catch { /* retry */ }
+        await new Promise(r => setTimeout(r, 1000));
+      }
+      if (!ok) {
+        phases.push({ name: "post-flight", status: "fail", message: "health did not return auth.ok=true within 10s" });
+        throw new Error("post-flight failed");
+      }
+      execSync(`curl -sf --max-time 3 http://127.0.0.1:${port}/v1/models > /dev/null`);
+      phases.push({ name: "post-flight", status: "ok" });
+    } else {
+      phases.push({ name: "post-flight", status: "skipped-mock" });
+    }
+
+    // Auto-GC old snapshots after successful upgrade (best-effort, never throws).
+    try {
+      const gc = gcSnapshots(homedir(), { keepCount: 5, keepDays: 30 });
+      if (gc.removed.length > 0) {
+        console.error(`[gc] removed ${gc.removed.length} old snapshots; kept ${gc.kept.length}`);
+      }
+    } catch (e) {
+      console.error(`[gc] warn: snapshot GC failed: ${e.message}`);
+    }
+
+    return { path: "upgrade", executed: true, changed: true, snapshotPath, phases };
+  } catch (err) {
+    if (snapshotPath && !err.snapshotPath) {
+      Object.assign(err, {
+        snapshotPath,
+        phases,
+        hint: "Working tree may be at new version. Run `ocp update --rollback` to restore from snapshot."
+      });
+    }
+    throw err;
+  }
+}
+
+async function runFreshInstall({ doctor, opts }) {
+  if (!opts.yes) {
+    throw new Error("fresh_install requires --yes for non-interactive execution (or run interactively and answer y)");
+  }
+  const steps = [];
+  for (const cmd of doctor.next_action.ai_executable) {
+    if (opts.mockExec) {
+      steps.push({ cmd, status: "skipped-mock" });
+    } else {
+      try {
+        execSync(cmd, { stdio: "inherit" });
+        steps.push({ cmd, status: "ok" });
+      } catch (e) {
+        const detail = e.stderr?.toString().trim() || e.message;
+        steps.push({ cmd, status: "fail", error: String(detail) });
+        throw Object.assign(new Error(`fresh_install step failed: ${cmd} — ${detail}`), { steps });
+      }
+    }
+  }
+  return { path: "fresh_install", executed: true, changed: true, steps };
+}
+
+async function runRollback(opts) {
+  const homeDir = opts.homeDir || homedir();
+  const snapshots = opts.mockSnapshots ?? listSnapshots(homeDir);
+
+  if (opts.gc) {
+    const result = gcSnapshots(homeDir, { dryRun: opts.dryRun });
+    return { path: opts.dryRun ? "rollback-gc-dry-run" : "rollback-gc", ...result };
+  }
+
+  if (opts.list) {
+    return { path: "rollback-list", snapshots };
+  }
+  if (snapshots.length === 0) {
+    throw new Error("no upgrade snapshots found in ~/.ocp/upgrade-snapshot-*");
+  }
+
+  const target = opts.snapshotPath
+    ? snapshots.find(s => s.path === opts.snapshotPath)
+    : snapshots[snapshots.length - 1];
+  if (!target) throw new Error(`snapshot not found: ${opts.snapshotPath} (must be inside ~/.ocp/upgrade-snapshot-*)`);
+
+  const meta = opts.mockSnapshotMeta ?? readSnapshot(target.path);
+  if (!meta.fromCommit) throw new Error(`snapshot ${target.path} has no from-commit.txt`);
+
+  const phases = [];
+  if (opts.dryRun) {
+    return {
+      path: "rollback-dry-run",
+      executed: false,
+      target: target.path,
+      plan: [
+        `git checkout ${meta.fromCommit}`,
+        `cp ${target.path}/plist ~/Library/LaunchAgents/dev.ocp.proxy.plist`,
+        `cp ${target.path}/db.bak ~/.ocp/ocp.db`,
+        `launchctl bootout/bootstrap`,
+        `ocp doctor`
+      ]
+    };
+  }
+
+  if (!opts.yes) throw new Error("rollback requires --yes for non-interactive execution");
+
+  const exec = (cmd, label) => {
+    if (opts.mockExec) {
+      phases.push({ name: label, cmd, status: "skipped-mock" });
+      return "";
+    }
+    try {
+      execSync(cmd, { stdio: ["pipe", "pipe", "pipe"] });
+      phases.push({ name: label, cmd, status: "ok" });
+    } catch (err) {
+      const detail = err.stderr?.toString().trim();
+      phases.push({ name: label, cmd, status: "fail", stderr: detail });
+      throw Object.assign(
+        new Error(`rollback phase ${label} failed: ${detail || err.message}`),
+        { phases, target: target.path }
+      );
+    }
+  };
+
+  const ocpDir = opts.ocpDir || join(homedir(), "ocp");
+  exec(`git -C ${ocpDir} checkout ${meta.fromCommit}`, "git-checkout");
+
+  if (!opts.mockExec) {
+    const tryCopy = (src, dst) => {
+      try {
+        if (existsSync(src)) copyFileSync(src, dst);
+      } catch (err) {
+        console.error(`[rollback] warn: could not restore ${src} → ${dst} (${err.code || err.message})`);
+      }
+    };
+    tryCopy(join(target.path, "plist"), join(homeDir, "Library", "LaunchAgents", "dev.ocp.proxy.plist"));
+    tryCopy(join(target.path, "service"), join(homeDir, ".config", "systemd", "user", "ocp-proxy.service"));
+    tryCopy(join(target.path, "db.bak"), join(homeDir, ".ocp", "ocp.db"));
+    tryCopy(join(target.path, "admin-key"), join(homeDir, ".ocp", "admin-key"));
+    phases.push({ name: "restore-files", status: "ok" });
+  } else {
+    phases.push({ name: "restore-files", status: "skipped-mock" });
+  }
+
+  exec(`npm --prefix ${ocpDir} install --no-audit --no-fund`, "npm-install");
+
+  if (!opts.mockExec) {
+    console.error(`[heads-up] restarting OCP service in 3s — expect ~5–10s blip on requests in flight.`);
+    await new Promise(r => setTimeout(r, 3000));
+  }
+  if (process.platform === "darwin") {
+    exec(`launchctl bootout gui/$(id -u)/dev.ocp.proxy 2>/dev/null || true`, "restart");
+    exec(`launchctl bootstrap gui/$(id -u) ${join(homedir(), "Library", "LaunchAgents", "dev.ocp.proxy.plist")}`, "restart");
+  } else {
+    exec(`systemctl --user restart ocp-proxy.service`, "restart");
+  }
+
+  return { path: "rollback", executed: true, changed: true, target: target.path, phases };
+}
+
+// CLI entrypoint — use fileURLToPath + realpath to handle symlinked install paths.
+import { fileURLToPath } from "node:url";
+import { realpathSync } from "node:fs";
+function _isMain() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+  } catch { return false; }
+}
+if (_isMain()) {
+  const args = process.argv.slice(2);
+  const dryRun = args.includes("--dry-run");
+  const yes = args.includes("--yes");
+  const rollback = args.includes("--rollback");
+  const list = args.includes("--list");
+  const gc = args.includes("--gc");
+  const targetIdx = args.indexOf("--target");
+  const target = targetIdx !== -1 ? args[targetIdx + 1] : undefined;
+  // First non-flag positional after --rollback is the snapshot path
+  let snapshotPath;
+  if (rollback) {
+    const rb = args.indexOf("--rollback");
+    const cand = args[rb + 1];
+    if (cand && !cand.startsWith("--")) snapshotPath = cand;
+  }
+  try {
+    const result = await runUpgrade({ dryRun, yes, rollback, list, gc, snapshotPath, target });
+    if (result.plan) for (const line of result.plan) console.log(line);
+    if (result.phases) for (const p of result.phases) console.log(`[${p.name}] ${p.status}${p.cmd ? `: ${p.cmd}` : ""}`);
+    if (result.steps) for (const s of result.steps) console.log(`  ${s.status === "ok" ? "✓" : s.status === "skipped-mock" ? "·" : "✗"} ${s.cmd}`);
+    if (result.snapshots) {
+      console.log(`Found ${result.snapshots.length} snapshots:`);
+      for (const s of result.snapshots) console.log(`  ${s.name}`);
+    }
+    if (result.removed && result.kept) {
+      console.log(`Snapshots: kept ${result.kept.length}, ${result.dryRun ? "would remove" : "removed"} ${result.removed.length}`);
+      for (const s of result.removed) console.log(`  - ${s.name}`);
+    }
+    process.exit(0);
+  } catch (e) {
+    console.error(`✗ ${e.message}`);
+    if (e.snapshotPath) console.error(`   snapshot: ${e.snapshotPath}`);
+    if (e.target) console.error(`   target: ${e.target}`);
+    if (e.hint) console.error(`   hint: ${e.hint}`);
+    process.exit(1);
+  }
+}

setup.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * openclaw-claude-proxy setup
+ * OCP (Open Claude Proxy) setup
  *
  * Automatically configures OpenClaw to use Claude CLI as a model provider.
  * Run: node setup.mjs [--port 3456] [--default-model opus|sonnet|haiku] [--dry-run]
@@ -12,7 +12,8 @@
  *   4. Creates start.sh for easy launch
  *   5. Optionally starts the proxy
  */
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, readdirSync, chmodSync } from "node:fs";
+import { mergePlistEnv, mergeSystemdEnv } from "./scripts/lib/plist-merge.mjs";
 import { execSync } from "node:child_process";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
@@ -36,50 +37,51 @@ const DEFAULT_MODEL = opt("default-model", "opus"); // opus | sonnet | haiku
 const DRY_RUN = flag("dry-run");
 const SKIP_START = flag("no-start");
 const PROVIDER_NAME = opt("provider-name", "claude-local");
+const BIND_ADDRESS = opt("bind", "127.0.0.1");
+const AUTH_MODE_CONFIG = opt("auth-mode", "none");
 
-const MODEL_ID_MAP = {
-  opus: "claude-opus-4-6",
-  sonnet: "claude-sonnet-4-6",
-  haiku: "claude-haiku-4",
-};
+// ── Service-env injection: CLAUDE_BIN, OCP_ADMIN_KEY, PROXY_ANONYMOUS_KEY ──
+// These are read from the user's shell env at install time and written into
+// the service unit (plist / systemd) so the daemon picks them up on boot.
+
+// CLAUDE_BIN — detect at install time; omit if not found (server.mjs fallback)
+let CLAUDE_BIN_INJECT = null;
+if (process.env.CLAUDE_BIN) {
+  CLAUDE_BIN_INJECT = process.env.CLAUDE_BIN;
+} else {
+  try {
+    const detected = execSync("which claude 2>/dev/null", { encoding: "utf-8" }).trim();
+    if (detected && existsSync(detected)) {
+      CLAUDE_BIN_INJECT = detected;
+    }
+  } catch { /* which not available or claude not on PATH — omit */ }
+}
+
+// OCP_ADMIN_KEY — omit entirely when empty/unset; don't write empty string
+const OCP_ADMIN_KEY_INJECT = process.env.OCP_ADMIN_KEY || null;
+
+// PROXY_ANONYMOUS_KEY — same pattern
+const PROXY_ANON_KEY_INJECT = process.env.PROXY_ANONYMOUS_KEY || null;
+
+// ── Models: derived from models.json (single source of truth) ──────────
+const modelsConfig = JSON.parse(readFileSync(join(__dirname, "models.json"), "utf-8"));
+
+const MODEL_ID_MAP = modelsConfig.aliases;
 const DEFAULT_MODEL_ID = MODEL_ID_MAP[DEFAULT_MODEL] || MODEL_ID_MAP.opus;
 
-// ── Models to register ──────────────────────────────────────────────────
-const MODELS = [
-  {
-    id: "claude-opus-4-6",
-    name: "Claude Opus 4.6 (via CLI)",
-    reasoning: true,
-    input: ["text"],
-    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-    contextWindow: 200000,
-    maxTokens: 16384,
-  },
-  {
-    id: "claude-sonnet-4-6",
-    name: "Claude Sonnet 4.6 (via CLI)",
-    reasoning: true,
-    input: ["text"],
-    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-    contextWindow: 200000,
-    maxTokens: 16384,
-  },
-  {
-    id: "claude-haiku-4",
-    name: "Claude Haiku 4 (via CLI)",
-    reasoning: false,
-    input: ["text"],
-    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-    contextWindow: 200000,
-    maxTokens: 8192,
-  },
-];
+const MODELS = modelsConfig.models.map(m => ({
+  id: m.id,
+  name: m.openclawName,
+  reasoning: m.reasoning,
+  input: ["text"],
+  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+  contextWindow: m.contextWindow,
+  maxTokens: m.maxTokens,
+}));
 
-const MODEL_ALIASES = {
-  [`${PROVIDER_NAME}/claude-opus-4-6`]: { alias: "Claude Opus 4.6" },
-  [`${PROVIDER_NAME}/claude-sonnet-4-6`]: { alias: "Claude Sonnet 4.6" },
-  [`${PROVIDER_NAME}/claude-haiku-4`]: { alias: "Claude Haiku 4" },
-};
+const MODEL_ALIASES = Object.fromEntries(
+  modelsConfig.models.map(m => [`${PROVIDER_NAME}/${m.id}`, { alias: m.displayName }])
+);
 
 // ── Helpers ─────────────────────────────────────────────────────────────
 function log(msg) { console.log(`  ✓ ${msg}`); }
@@ -129,93 +131,112 @@ try {
   warn("Make sure you're logged in: claude login");
 }
 
-// Check openclaw config
-if (!existsSync(CONFIG_PATH)) fail(`OpenClaw config not found at ${CONFIG_PATH}`);
-log(`OpenClaw config: ${CONFIG_PATH}`);
+// Check openclaw config (optional — OCP runs standalone without OpenClaw)
+const OPENCLAW_PRESENT = existsSync(CONFIG_PATH);
+if (OPENCLAW_PRESENT) {
+  log(`OpenClaw config: ${CONFIG_PATH}`);
+} else {
+  warn(`OpenClaw not detected at ${CONFIG_PATH} — skipping OpenClaw integration.`);
+  warn(`To register OCP with OpenClaw later, install OpenClaw and re-run \`node setup.mjs\`,`);
+  warn(`or run \`ocp update\` if OpenClaw is installed afterward.`);
+}
 
 // ── Step 2: Patch openclaw.json ─────────────────────────────────────────
-console.log("\n📝 Configuring OpenClaw...\n");
+if (OPENCLAW_PRESENT) {
+  console.log("\n📝 Configuring OpenClaw...\n");
 
-const config = readJSON(CONFIG_PATH);
+  const config = readJSON(CONFIG_PATH);
 
-// Ensure models.providers exists
-if (!config.models) config.models = {};
-if (!config.models.providers) config.models.providers = {};
+  // Ensure models.providers exists
+  if (!config.models) config.models = {};
+  if (!config.models.providers) config.models.providers = {};
 
-// Add/update claude-local provider
-config.models.providers[PROVIDER_NAME] = {
-  baseUrl: `http://127.0.0.1:${PORT}/v1`,
-  api: "openai-completions",
-  authHeader: false,
-  models: MODELS,
-};
-log(`Provider "${PROVIDER_NAME}" → http://127.0.0.1:${PORT}/v1`);
+  // Add/update claude-local provider
+  config.models.providers[PROVIDER_NAME] = {
+    baseUrl: `http://127.0.0.1:${PORT}/v1`,
+    api: "openai-completions",
+    authHeader: false,
+    models: MODELS,
+  };
+  log(`Provider "${PROVIDER_NAME}" → http://127.0.0.1:${PORT}/v1`);
 
-// Ensure auth profile in config
-if (!config.auth) config.auth = {};
-if (!config.auth.profiles) config.auth.profiles = {};
-config.auth.profiles[`${PROVIDER_NAME}:default`] = {
-  provider: PROVIDER_NAME,
-  mode: "api_key",
-};
-log(`Auth profile "${PROVIDER_NAME}:default" registered`);
+  // Ensure auth profile in config
+  if (!config.auth) config.auth = {};
+  if (!config.auth.profiles) config.auth.profiles = {};
+  config.auth.profiles[`${PROVIDER_NAME}:default`] = {
+    provider: PROVIDER_NAME,
+    mode: "api_key",
+  };
+  log(`Auth profile "${PROVIDER_NAME}:default" registered`);
 
-// Add models to agents.defaults.models
-if (!config.agents) config.agents = {};
-if (!config.agents.defaults) config.agents.defaults = {};
-if (!config.agents.defaults.models) config.agents.defaults.models = {};
-for (const [key, val] of Object.entries(MODEL_ALIASES)) {
-  config.agents.defaults.models[key] = val;
-}
-log(`Model aliases added to agents.defaults.models`);
-
-writeJSON(CONFIG_PATH, config);
-log(`Config saved`);
-
-// ── Step 3: Patch auth-profiles.json ────────────────────────────────────
-console.log("\n🔑 Configuring auth profiles...\n");
-
-// Find all agent auth-profiles.json files
-const agentsDir = join(OPENCLAW_DIR, "agents");
-const agentDirs = existsSync(agentsDir)
-  ? readdirSync(agentsDir).filter((d) => {
-      const ap = join(agentsDir, d, "agent", "auth-profiles.json");
-      return existsSync(ap);
-    })
-  : [];
-
-import { readdirSync } from "node:fs";
-
-for (const agentId of agentDirs) {
-  const apPath = join(agentsDir, agentId, "agent", "auth-profiles.json");
-  try {
-    const ap = readJSON(apPath);
-    if (!ap.profiles) ap.profiles = {};
-
-    // Add claude-local profile if missing
-    if (!ap.profiles[`${PROVIDER_NAME}:default`]) {
-      ap.profiles[`${PROVIDER_NAME}:default`] = {
-        type: "api_key",
-        provider: PROVIDER_NAME,
-        key: "local-proxy-no-auth",
-      };
-    }
-
-    // Add to lastGood if missing
-    if (!ap.lastGood) ap.lastGood = {};
-    if (!ap.lastGood[PROVIDER_NAME]) {
-      ap.lastGood[PROVIDER_NAME] = `${PROVIDER_NAME}:default`;
-    }
-
-    writeJSON(apPath, ap);
-    log(`Agent "${agentId}" auth profile updated`);
-  } catch (e) {
-    warn(`Skipped agent "${agentId}": ${e.message}`);
+  // Add models to agents.defaults.models
+  if (!config.agents) config.agents = {};
+  if (!config.agents.defaults) config.agents.defaults = {};
+  if (!config.agents.defaults.models) config.agents.defaults.models = {};
+  for (const [key, val] of Object.entries(MODEL_ALIASES)) {
+    config.agents.defaults.models[key] = val;
   }
-}
+  log(`Model aliases added to agents.defaults.models`);
 
-if (agentDirs.length === 0) {
-  warn("No agent auth-profiles.json found — you may need to restart the gateway first");
+  // Set idleTimeoutSeconds to 0 — critical for Claude tool-use.
+  // When Claude calls tools (Bash, Read, etc.), the token stream pauses for 30-120s.
+  // OpenClaw's default idleTimeoutSeconds (60s) kills the connection mid-tool-call,
+  // causing exit 143 (SIGTERM) and stuck sessions. Setting to 0 disables the idle timer.
+  if (!config.agents.defaults.llm) config.agents.defaults.llm = {};
+  if (config.agents.defaults.llm.idleTimeoutSeconds === undefined ||
+      config.agents.defaults.llm.idleTimeoutSeconds > 0) {
+    config.agents.defaults.llm.idleTimeoutSeconds = 0;
+    log(`Set agents.defaults.llm.idleTimeoutSeconds = 0 (prevents tool-call timeouts)`);
+  } else {
+    log(`idleTimeoutSeconds already configured: ${config.agents.defaults.llm.idleTimeoutSeconds}`);
+  }
+
+  writeJSON(CONFIG_PATH, config);
+  log(`Config saved`);
+
+  // ── Step 3: Patch auth-profiles.json ────────────────────────────────────
+  console.log("\n🔑 Configuring auth profiles...\n");
+
+  // Find all agent auth-profiles.json files
+  const agentsDir = join(OPENCLAW_DIR, "agents");
+  const agentDirs = existsSync(agentsDir)
+    ? readdirSync(agentsDir).filter((d) => {
+        const ap = join(agentsDir, d, "agent", "auth-profiles.json");
+        return existsSync(ap);
+      })
+    : [];
+
+  for (const agentId of agentDirs) {
+    const apPath = join(agentsDir, agentId, "agent", "auth-profiles.json");
+    try {
+      const ap = readJSON(apPath);
+      if (!ap.profiles) ap.profiles = {};
+
+      // Add claude-local profile if missing
+      if (!ap.profiles[`${PROVIDER_NAME}:default`]) {
+        ap.profiles[`${PROVIDER_NAME}:default`] = {
+          type: "api_key",
+          provider: PROVIDER_NAME,
+          key: "local-proxy-no-auth",
+        };
+      }
+
+      // Add to lastGood if missing
+      if (!ap.lastGood) ap.lastGood = {};
+      if (!ap.lastGood[PROVIDER_NAME]) {
+        ap.lastGood[PROVIDER_NAME] = `${PROVIDER_NAME}:default`;
+      }
+
+      writeJSON(apPath, ap);
+      log(`Agent "${agentId}" auth profile updated`);
+    } catch (e) {
+      warn(`Skipped agent "${agentId}": ${e.message}`);
+    }
+  }
+
+  if (agentDirs.length === 0) {
+    warn("No agent auth-profiles.json found — you may need to restart the gateway first");
+  }
 }
 
 // ── Step 4: Create start.sh ─────────────────────────────────────────────
@@ -226,7 +247,7 @@ const logDir = join(OPENCLAW_DIR, "logs");
 if (!existsSync(logDir)) mkdirSync(logDir, { recursive: true });
 
 const startSh = `#!/bin/bash
-# Start openclaw-claude-proxy if not already running
+# Start OCP (Open Claude Proxy) if not already running
 PORT=\${CLAUDE_PROXY_PORT:-${PORT}}
 if ! lsof -i :\$PORT -sTCP:LISTEN &>/dev/null; then
   unset CLAUDECODE
@@ -247,64 +268,131 @@ if (!DRY_RUN) {
 log(`Launcher: ${startPath}`);
 
 // ── Step 5: Summary ─────────────────────────────────────────────────────
-console.log(`
-╔══════════════════════════════════════════════════════════════╗
-║                  Setup complete!                             ║
-╠══════════════════════════════════════════════════════════════╣
-║                                                              ║
-║  Provider: ${PROVIDER_NAME.padEnd(44)}║
-║  Port:     ${String(PORT).padEnd(44)}║
-║  Models:   claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4║
-║  Default:  ${DEFAULT_MODEL_ID.padEnd(44)}║
-║                                                              ║
-║  Start proxy:                                                ║
-║    bash ${startPath.replace(HOME, "~").padEnd(50)}║
-║                                                              ║
-║  Or directly:                                                ║
-║    node ${serverPath.replace(HOME, "~").padEnd(49)}║
-║                                                              ║
-║  Set as default model in openclaw.json:                      ║
-║    agents.defaults.model.primary =                           ║
-║      "${PROVIDER_NAME}/${DEFAULT_MODEL_ID}"${" ".repeat(Math.max(0, 30 - PROVIDER_NAME.length - DEFAULT_MODEL_ID.length))}║
-║                                                              ║
-║  Then restart gateway:                                       ║
-║    openclaw gateway restart                                  ║
-║                                                              ║
-╚══════════════════════════════════════════════════════════════╝
-`);
-
-// ── Step 6: Optionally start ────────────────────────────────────────────
-if (!SKIP_START && !DRY_RUN) {
-  try {
-    execSync(`bash "${startPath}"`, { stdio: "inherit" });
-  } catch { /* ignore */ }
+const banner = [
+  `╔══════════════════════════════════════════════════════════════╗`,
+  `║                  Setup complete!                             ║`,
+  `╠══════════════════════════════════════════════════════════════╣`,
+  `║                                                              ║`,
+  `║  Provider: ${PROVIDER_NAME.padEnd(44)}║`,
+  `║  Port:     ${String(PORT).padEnd(44)}║`,
+  `║  Models:   ${`see models.json (${MODELS.length} available)`.padEnd(44)}║`,
+  `║  Default:  ${DEFAULT_MODEL_ID.padEnd(44)}║`,
+  `║                                                              ║`,
+  `║  Start proxy:                                                ║`,
+  `║    bash ${startPath.replace(HOME, "~").padEnd(50)}║`,
+  `║                                                              ║`,
+  `║  Or directly:                                                ║`,
+  `║    node ${serverPath.replace(HOME, "~").padEnd(49)}║`,
+  `║                                                              ║`,
+];
+if (OPENCLAW_PRESENT) {
+  banner.push(
+    `║  Set as default model in openclaw.json:                      ║`,
+    `║    agents.defaults.model.primary =                           ║`,
+    `║      "${PROVIDER_NAME}/${DEFAULT_MODEL_ID}"${" ".repeat(Math.max(0, 30 - PROVIDER_NAME.length - DEFAULT_MODEL_ID.length))}║`,
+    `║                                                              ║`,
+    `║  Then restart gateway:                                       ║`,
+    `║    openclaw gateway restart                                  ║`,
+    `║                                                              ║`,
+  );
+} else {
+  banner.push(
+    `║  OpenClaw not detected — running in standalone mode.         ║`,
+    `║  Point your IDE (Cline / Cursor / Continue / OpenCode /      ║`,
+    `║  Aider / OpenClaw) at:                                       ║`,
+    `║    http://${BIND_ADDRESS}:${String(PORT)}/v1${" ".repeat(Math.max(0, 47 - BIND_ADDRESS.length - String(PORT).length))}║`,
+    `║                                                              ║`,
+    `║  See README § "Client Setup" for per-IDE instructions.       ║`,
+    `║                                                              ║`,
+  );
 }
+banner.push(`╚══════════════════════════════════════════════════════════════╝`);
+console.log("\n" + banner.join("\n") + "\n");
 
 // ── Step 7: Install auto-start on boot ──────────────────────────────────
+
+// Log service-env injection plan (shown in both dry-run and live mode)
+console.log("\n🔧 Service unit env vars to inject:\n");
+if (CLAUDE_BIN_INJECT) {
+  log(`CLAUDE_BIN: ${CLAUDE_BIN_INJECT}`);
+} else {
+  log(`CLAUDE_BIN: (not found — server.mjs will auto-detect at runtime)`);
+}
+if (OCP_ADMIN_KEY_INJECT) {
+  log(`OCP_ADMIN_KEY: injected (length: ${OCP_ADMIN_KEY_INJECT.length})`);
+} else {
+  log(`OCP_ADMIN_KEY: (unset — admin endpoints disabled)`);
+}
+if (PROXY_ANON_KEY_INJECT) {
+  log(`PROXY_ANONYMOUS_KEY: injected (set)`);
+} else {
+  log(`PROXY_ANONYMOUS_KEY: (unset — anonymous access disabled)`);
+}
+
+if (DRY_RUN) {
+  console.log("\n  [dry-run] would write service unit with above env vars\n");
+}
+
 if (!DRY_RUN) {
   console.log("\n🔄 Installing auto-start on login...\n");
 
   const platform = process.platform;
-  const nodeBin = process.execPath;
+  // Use stable symlink path instead of versioned Cellar path (e.g. /opt/homebrew/opt/node/bin/node
+  // instead of /opt/homebrew/Cellar/node/25.8.0/bin/node) so the plist survives node upgrades.
+  let nodeBin = process.execPath;
+  if (platform === "darwin" && nodeBin.includes("/Cellar/")) {
+    const stable = nodeBin.replace(/\/Cellar\/[^/]+\/[^/]+\//, "/opt/");
+    if (existsSync(stable)) {
+      nodeBin = stable;
+      log(`Using stable node path: ${nodeBin}`);
+    }
+  }
 
   // Ensure logs dir exists
   const logsDir = join(OPENCLAW_DIR, "logs");
   if (!existsSync(logsDir)) mkdirSync(logsDir, { recursive: true });
 
+  // Use neutral service names to avoid OpenClaw gateway's extra-service detection.
+  // OpenClaw scans LaunchAgent plists and systemd units for "openclaw" / "clawdbot"
+  // markers and flags them as conflicting gateway-like services. Using "dev.ocp.*"
+  // and "ocp-proxy" keeps the proxy invisible to that heuristic.
+  const OCP_HOME = join(HOME, ".ocp");
+  const ocpLogsDir = join(OCP_HOME, "logs");
+  if (!existsSync(ocpLogsDir)) mkdirSync(ocpLogsDir, { recursive: true });
+
+  // Uninstall legacy service names if present (upgrade path)
+  if (platform === "darwin") {
+    const legacyPlist = join(HOME, "Library", "LaunchAgents", "ai.openclaw.proxy.plist");
+    if (existsSync(legacyPlist)) {
+      try { execSync(`launchctl bootout gui/$(id -u) "${legacyPlist}" 2>/dev/null`); } catch { /* ignore */ }
+      try { unlinkSync(legacyPlist); } catch { /* ignore */ }
+      log(`Removed legacy plist: ai.openclaw.proxy`);
+    }
+  } else if (platform === "linux") {
+    const legacyService = join(HOME, ".config", "systemd", "user", "openclaw-proxy.service");
+    if (existsSync(legacyService)) {
+      try { execSync(`systemctl --user stop openclaw-proxy 2>/dev/null`); } catch { /* ignore */ }
+      try { execSync(`systemctl --user disable openclaw-proxy 2>/dev/null`); } catch { /* ignore */ }
+      try { unlinkSync(legacyService); } catch { /* ignore */ }
+      try { execSync(`systemctl --user daemon-reload`); } catch { /* ignore */ }
+      log(`Removed legacy systemd service: openclaw-proxy`);
+    }
+  }
+
   if (platform === "darwin") {
     // macOS: launchd
     const plistDir = join(HOME, "Library", "LaunchAgents");
     if (!existsSync(plistDir)) mkdirSync(plistDir, { recursive: true });
 
-    const plistPath = join(plistDir, "ai.openclaw.proxy.plist");
-    const logPath = join(logsDir, "proxy.log");
+    const plistPath = join(plistDir, "dev.ocp.proxy.plist");
+    const logPath = join(ocpLogsDir, "proxy.log");
 
     const plistXml = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
   <key>Label</key>
-  <string>ai.openclaw.proxy</string>
+  <string>dev.ocp.proxy</string>
   <key>ProgramArguments</key>
   <array>
     <string>${nodeBin}</string>
@@ -314,6 +402,16 @@ if (!DRY_RUN) {
   <dict>
     <key>CLAUDE_PROXY_PORT</key>
     <string>${PORT}</string>
+    <key>CLAUDE_BIND</key>
+    <string>${BIND_ADDRESS}</string>
+    <key>CLAUDE_AUTH_MODE</key>
+    <string>${AUTH_MODE_CONFIG}</string>${CLAUDE_BIN_INJECT ? `
+    <key>CLAUDE_BIN</key>
+    <string>${CLAUDE_BIN_INJECT}</string>` : ""}${OCP_ADMIN_KEY_INJECT ? `
+    <key>OCP_ADMIN_KEY</key>
+    <string>${OCP_ADMIN_KEY_INJECT}</string>` : ""}${PROXY_ANON_KEY_INJECT ? `
+    <key>PROXY_ANONYMOUS_KEY</key>
+    <string>${PROXY_ANON_KEY_INJECT}</string>` : ""}
   </dict>
   <key>RunAtLoad</key>
   <true/>
@@ -327,30 +425,40 @@ if (!DRY_RUN) {
 </plist>
 `;
 
-    writeFileSync(plistPath, plistXml);
-    log(`Plist written: ${plistPath}`);
+    const existingPlist = existsSync(plistPath) ? readFileSync(plistPath, "utf8") : null;
+    const finalPlistXml = mergePlistEnv(existingPlist, plistXml);
+    writeFileSync(plistPath, finalPlistXml);
+    chmodSync(plistPath, 0o600);
+    if (existingPlist && finalPlistXml !== plistXml) {
+      log(`Plist written: ${plistPath} (mode 600, preserved user env vars)`);
+    } else {
+      log(`Plist written: ${plistPath} (mode 600)`);
+    }
 
-    // Unload first (in case it was already loaded) then load
-    try { execSync(`launchctl unload "${plistPath}" 2>/dev/null`); } catch { /* ignore */ }
-    execSync(`launchctl load "${plistPath}"`);
-    log(`launchctl loaded ai.openclaw.proxy`);
+    // Bootout first (in case it was already loaded) then bootstrap
+    try { execSync(`launchctl bootout gui/$(id -u) "${plistPath}" 2>/dev/null`); } catch { /* ignore */ }
+    execSync(`launchctl bootstrap gui/$(id -u) "${plistPath}"`);
+    log(`launchctl loaded dev.ocp.proxy`);
 
   } else if (platform === "linux") {
     // Linux: systemd user service
     const systemdDir = join(HOME, ".config", "systemd", "user");
     if (!existsSync(systemdDir)) mkdirSync(systemdDir, { recursive: true });
 
-    const servicePath = join(systemdDir, "openclaw-proxy.service");
-    const logPath = join(logsDir, "proxy.log");
+    const servicePath = join(systemdDir, "ocp-proxy.service");
+    const logPath = join(ocpLogsDir, "proxy.log");
 
     const serviceUnit = `[Unit]
-Description=OpenClaw Claude Proxy
+Description=OCP — Open Claude Proxy
 After=network.target
 
 [Service]
 ExecStart=${nodeBin} ${serverPath}
 Environment=CLAUDE_PROXY_PORT=${PORT}
+Environment=CLAUDE_BIND=${BIND_ADDRESS}
+Environment=CLAUDE_AUTH_MODE=${AUTH_MODE_CONFIG}${CLAUDE_BIN_INJECT ? `\nEnvironment=CLAUDE_BIN=${CLAUDE_BIN_INJECT}` : ""}${OCP_ADMIN_KEY_INJECT ? `\nEnvironment=OCP_ADMIN_KEY=${OCP_ADMIN_KEY_INJECT}` : ""}${PROXY_ANON_KEY_INJECT ? `\nEnvironment=PROXY_ANONYMOUS_KEY=${PROXY_ANON_KEY_INJECT}` : ""}
 Restart=always
+RestartSec=5
 StandardOutput=append:${logPath}
 StandardError=append:${logPath}
 
@@ -358,12 +466,19 @@ StandardError=append:${logPath}
 WantedBy=default.target
 `;
 
-    writeFileSync(servicePath, serviceUnit);
-    log(`Service file written: ${servicePath}`);
+    const existingService = existsSync(servicePath) ? readFileSync(servicePath, "utf8") : null;
+    const finalServiceUnit = mergeSystemdEnv(existingService, serviceUnit);
+    writeFileSync(servicePath, finalServiceUnit);
+    chmodSync(servicePath, 0o600);
+    if (existingService && finalServiceUnit !== serviceUnit) {
+      log(`Service file written: ${servicePath} (mode 600, preserved user env vars)`);
+    } else {
+      log(`Service file written: ${servicePath} (mode 600)`);
+    }
 
     execSync(`systemctl --user daemon-reload`);
-    execSync(`systemctl --user enable openclaw-proxy`);
-    execSync(`systemctl --user start openclaw-proxy`);
+    execSync(`systemctl --user enable ocp-proxy`);
+    execSync(`systemctl --user start ocp-proxy`);
     log(`systemd user service enabled and started`);
 
   } else {
@@ -371,4 +486,52 @@ WantedBy=default.target
   }
 
   console.log("\n✅ Auto-start installed — proxy will start automatically on login\n");
+
+  // ── Step 8: Post-install health verification ───────────────────────────
+  if (!SKIP_START) {
+    console.log("⏳ Waiting for server to bind...\n");
+    await new Promise(r => setTimeout(r, 3000));
+
+    const healthUrl = `http://127.0.0.1:${PORT}/health`;
+    let verified = false;
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), 5000);
+      const res = await fetch(healthUrl, { signal: controller.signal });
+      clearTimeout(timer);
+
+      if (res.ok) {
+        const body = await res.json().catch(() => ({}));
+        console.log(`  ✓ Health check passed (${healthUrl})`);
+        console.log(`    version:  ${body.version ?? "unknown"}`);
+        console.log(`    authMode: ${body.authMode ?? "unknown"}`);
+
+        // Verify bind socket
+        try {
+          const bindCheck = process.platform === "linux"
+            ? execSync(`ss -tlnp 2>/dev/null | grep ':${PORT}'`, { encoding: "utf-8" }).trim()
+            : execSync(`lsof -nP -iTCP:${PORT} -sTCP:LISTEN 2>/dev/null`, { encoding: "utf-8" }).trim();
+          if (bindCheck) {
+            console.log(`    bind:     ${bindCheck.split("\n")[0]}`);
+          }
+        } catch { /* bind check is best-effort */ }
+
+        verified = true;
+      } else {
+        warn(`Health check returned HTTP ${res.status} — service may not have started cleanly`);
+      }
+    } catch (e) {
+      const isTimeout = e.name === "AbortError" || (e.cause && e.cause.code === "UND_ERR_CONNECT_TIMEOUT");
+      warn(`Health check failed: ${isTimeout ? "timeout (5s)" : e.message}`);
+    }
+
+    if (!verified) {
+      const logHint = process.platform === "linux"
+        ? "journalctl --user -u ocp-proxy -n 50"
+        : `tail -n 100 ~/.ocp/logs/proxy.log`;
+      console.error(`\n  ✗ Server did not respond on port ${PORT} within 5 seconds.`);
+      console.error(`    Check service logs:\n      ${logHint}\n`);
+      process.exit(1);
+    }
+  }
 }

start.sh

@@ -1,12 +0,0 @@
-#!/bin/bash
-# Start openclaw-claude-proxy if not already running
-PORT=${CLAUDE_PROXY_PORT:-3456}
-if ! lsof -i :$PORT -sTCP:LISTEN &>/dev/null; then
-  unset CLAUDECODE
-  nohup node "/Users/taodeng/.openclaw/projects/claude-proxy/openclaw-claude-proxy/server.mjs" \
-    >> "/Users/taodeng/.openclaw/logs/claude-proxy.log" \
-    2>> "/Users/taodeng/.openclaw/logs/claude-proxy.err.log" &
-  echo "claude-proxy started on port $PORT (pid $!)"
-else
-  echo "claude-proxy already running on port $PORT"
-fi

test-features.mjs

@@ -0,0 +1,958 @@
+#!/usr/bin/env node
+/**
+ * Integration test for Quota + Cache features.
+ * Tests database layer functions directly — no server needed.
+ */
+import { getDb, createKey, listKeys, validateKey, recordUsage, checkQuota, updateKeyQuota, getKeyQuota, findKey, cacheHash, getCachedResponse, setCachedResponse, clearCache, getCacheStats, closeDb, hasCacheControl, singleflight, getInflightStats } from "./keys.mjs";
+import { createHash } from "node:crypto";
+import { strict as assert } from "node:assert";
+import { unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+// Use a test database to avoid corrupting real data
+const TEST_DB = join(homedir(), ".ocp", "ocp-test.db");
+try { unlinkSync(TEST_DB); } catch {}
+
+// Monkey-patch DB_PATH for testing (override the module-level variable)
+// Since keys.mjs uses lazy init, we can set env before first getDb() call
+process.env.HOME = homedir(); // ensure consistent
+
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+  try {
+    fn();
+    passed++;
+    console.log(`  ✓ ${name}`);
+  } catch (e) {
+    failed++;
+    console.log(`  ✗ ${name}: ${e.message}`);
+  }
+}
+
+console.log("\n=== OCP Feature Tests (Quota + Cache) ===\n");
+
+// Initialize DB
+const db = getDb();
+
+// ── Quota Tests ──
+console.log("Quota:");
+
+const key1 = createKey("test-user-1");
+const key2 = createKey("test-user-2");
+
+test("createKey returns id, key, name", () => {
+  assert.ok(key1.id);
+  assert.ok(key1.key.startsWith("ocp_"));
+  assert.equal(key1.name, "test-user-1");
+});
+
+test("listKeys includes quota fields", () => {
+  const keys = listKeys();
+  assert.ok(keys.length >= 2);
+  const k = keys.find(k => k.name === "test-user-1");
+  assert.ok("quota_daily" in k);
+  assert.ok("quota_weekly" in k);
+  assert.ok("quota_monthly" in k);
+  assert.equal(k.quota_daily, null);
+});
+
+test("checkQuota returns null when no quota set", () => {
+  const result = checkQuota(key1.id, key1.name);
+  assert.equal(result, null);
+});
+
+test("checkQuota returns null for null keyId", () => {
+  assert.equal(checkQuota(null, "anon"), null);
+  assert.equal(checkQuota(undefined, "anon"), null);
+});
+
+test("updateKeyQuota sets daily quota (partial update)", () => {
+  const ok = updateKeyQuota(key1.id, { daily: 5 });
+  assert.ok(ok);
+  const quota = getKeyQuota(key1.id);
+  assert.equal(quota.daily.limit, 5);
+  assert.equal(quota.weekly.limit, null); // not touched
+  assert.equal(quota.monthly.limit, null);
+});
+
+test("updateKeyQuota partial update preserves existing values", () => {
+  updateKeyQuota(key1.id, { weekly: 20 });
+  const quota = getKeyQuota(key1.id);
+  assert.equal(quota.daily.limit, 5);  // preserved from previous call
+  assert.equal(quota.weekly.limit, 20);
+});
+
+test("checkQuota passes when under limit", () => {
+  // Record 3 usages (limit is 5 daily)
+  for (let i = 0; i < 3; i++) {
+    recordUsage({ keyId: key1.id, keyName: key1.name, model: "sonnet", promptChars: 100, responseChars: 50, elapsedMs: 1000, success: true });
+  }
+  const result = checkQuota(key1.id, key1.name);
+  assert.equal(result, null);
+});
+
+test("checkQuota returns exceeded when at limit", () => {
+  // Record 2 more to hit limit (3 + 2 = 5)
+  for (let i = 0; i < 2; i++) {
+    recordUsage({ keyId: key1.id, keyName: key1.name, model: "sonnet", promptChars: 100, responseChars: 50, elapsedMs: 1000, success: true });
+  }
+  const result = checkQuota(key1.id, key1.name);
+  assert.ok(result);
+  assert.equal(result.period, "daily");
+  assert.equal(result.limit, 5);
+  assert.equal(result.used, 5);
+  assert.ok(result.resetsIn);
+});
+
+test("checkQuota ignores failed requests in count", () => {
+  // key2 has quota of 2 daily
+  updateKeyQuota(key2.id, { daily: 2 });
+  recordUsage({ keyId: key2.id, keyName: key2.name, model: "sonnet", promptChars: 100, responseChars: 0, elapsedMs: 500, success: false });
+  recordUsage({ keyId: key2.id, keyName: key2.name, model: "sonnet", promptChars: 100, responseChars: 50, elapsedMs: 1000, success: true });
+  const result = checkQuota(key2.id, key2.name);
+  assert.equal(result, null); // only 1 successful, limit is 2
+});
+
+test("getKeyQuota returns correct used counts", () => {
+  const quota = getKeyQuota(key1.id);
+  assert.equal(quota.daily.used, 5);
+  assert.equal(quota.daily.limit, 5);
+});
+
+test("findKey works by id and name", () => {
+  const byId = findKey(String(key1.id));
+  assert.ok(byId);
+  assert.equal(byId.name, "test-user-1");
+  const byName = findKey("test-user-1");
+  assert.ok(byName);
+  // Compare by name since auto-increment IDs may vary across runs
+  assert.equal(byName.name, "test-user-1");
+  assert.equal(findKey("nonexistent"), null);
+});
+
+// ── Cache Tests ──
+console.log("\nCache:");
+
+// Clean slate for cache tests
+clearCache();
+
+const msgs1 = [{ role: "user", content: "Hello world" }];
+const msgs2 = [{ role: "user", content: "Different prompt" }];
+
+test("cacheHash is deterministic", () => {
+  const h1 = cacheHash("sonnet", msgs1);
+  const h2 = cacheHash("sonnet", msgs1);
+  assert.equal(h1, h2);
+});
+
+test("cacheHash differs for different models", () => {
+  const h1 = cacheHash("sonnet", msgs1);
+  const h2 = cacheHash("opus", msgs1);
+  assert.notEqual(h1, h2);
+});
+
+test("cacheHash differs for different messages", () => {
+  const h1 = cacheHash("sonnet", msgs1);
+  const h2 = cacheHash("sonnet", msgs2);
+  assert.notEqual(h1, h2);
+});
+
+test("cacheHash includes temperature in hash", () => {
+  const h1 = cacheHash("sonnet", msgs1, {});
+  const h2 = cacheHash("sonnet", msgs1, { temperature: 0.5 });
+  const h3 = cacheHash("sonnet", msgs1, { temperature: 1.0 });
+  assert.notEqual(h1, h2);
+  assert.notEqual(h2, h3);
+});
+
+test("cacheHash includes max_tokens in hash", () => {
+  const h1 = cacheHash("sonnet", msgs1, {});
+  const h2 = cacheHash("sonnet", msgs1, { max_tokens: 100 });
+  assert.notEqual(h1, h2);
+});
+
+test("getCachedResponse returns null for miss", () => {
+  const hash = cacheHash("sonnet", msgs1);
+  const result = getCachedResponse(hash, 3600000);
+  assert.equal(result, null);
+});
+
+test("setCachedResponse + getCachedResponse roundtrip", () => {
+  const hash = cacheHash("sonnet", msgs1);
+  setCachedResponse(hash, "sonnet", "Hello! I am Claude.");
+  const result = getCachedResponse(hash, 3600000);
+  assert.ok(result);
+  assert.equal(result.response, "Hello! I am Claude.");
+  assert.equal(result.hits, 1);
+});
+
+test("getCachedResponse increments hit counter", () => {
+  const hash = cacheHash("sonnet", msgs1);
+  const r1 = getCachedResponse(hash, 3600000);
+  const r2 = getCachedResponse(hash, 3600000);
+  assert.equal(r1.hits, 2);
+  assert.equal(r2.hits, 3);
+});
+
+test("getCachedResponse respects TTL (expired entry)", () => {
+  // Insert a backdated cache entry directly
+  const d = getDb();
+  const oldHash = "test_expired_hash_12345";
+  d.prepare("INSERT OR REPLACE INTO response_cache (hash, model, response, created_at) VALUES (?, ?, ?, datetime('now', '-2 hours'))").run(oldHash, "sonnet", "Old response");
+  // TTL of 1 hour should not return a 2-hour-old entry
+  const result = getCachedResponse(oldHash, 3600000);
+  assert.equal(result, null);
+  // Clean up the backdated entry so it doesn't affect subsequent tests
+  d.prepare("DELETE FROM response_cache WHERE hash = ?").run(oldHash);
+});
+
+test("getCacheStats returns correct counts", () => {
+  const stats = getCacheStats();
+  assert.equal(stats.entries, 1);
+  assert.ok(stats.totalHits >= 3);
+  assert.ok(stats.sizeBytes > 0);
+});
+
+test("setCachedResponse upserts on conflict", () => {
+  const hash = cacheHash("sonnet", msgs1);
+  setCachedResponse(hash, "sonnet", "Updated response!");
+  const result = getCachedResponse(hash, 3600000);
+  assert.equal(result.response, "Updated response!");
+  assert.equal(result.hits, 1); // reset after upsert
+});
+
+test("clearCache removes all entries", () => {
+  // Add another entry
+  const hash2 = cacheHash("sonnet", msgs2);
+  setCachedResponse(hash2, "sonnet", "Another response");
+  const statsBefore = getCacheStats();
+  assert.equal(statsBefore.entries, 2);
+
+  const cleared = clearCache();
+  assert.equal(cleared, 2);
+
+  const statsAfter = getCacheStats();
+  assert.equal(statsAfter.entries, 0);
+});
+
+test("clearCache with TTL only removes old entries", () => {
+  // Add fresh entry
+  const hash = cacheHash("sonnet", msgs1);
+  setCachedResponse(hash, "sonnet", "Fresh response");
+
+  // Clear with TTL of 1 hour — fresh entry should survive
+  const cleared = clearCache(3600000);
+  assert.equal(cleared, 0);
+
+  const stats = getCacheStats();
+  assert.equal(stats.entries, 1);
+
+  // Clean up
+  clearCache();
+});
+
+// ── PR-A: Per-key isolation (D1), cache_control bypass (D2), chunked replay (D3) ──
+console.log("\nPR-A Cache Upgrade:");
+
+const msgsBase = [{ role: "user", content: "Shared prompt text" }];
+
+test("D1: cacheHash with two distinct keyIds produces different hashes", () => {
+  const h1 = cacheHash("sonnet", msgsBase, { keyId: "key-aaa" });
+  const h2 = cacheHash("sonnet", msgsBase, { keyId: "key-bbb" });
+  assert.notEqual(h1, h2);
+});
+
+test("D1: cacheHash with keyId=undefined and keyId='anon' produce the same hash", () => {
+  const hUndef = cacheHash("sonnet", msgsBase, { keyId: undefined });
+  const hAnon  = cacheHash("sonnet", msgsBase, { keyId: "anon" });
+  assert.equal(hUndef, hAnon);
+});
+
+test("D1: cacheHash with keyId=null and keyId='anon' produce the same hash", () => {
+  const hNull = cacheHash("sonnet", msgsBase, { keyId: null });
+  const hAnon = cacheHash("sonnet", msgsBase, { keyId: "anon" });
+  assert.equal(hNull, hAnon);
+});
+
+test("D1: v2 prefix — hash differs from a v1-style baseline (no prefix)", () => {
+  // Reproduce a v1-style hash manually to confirm v2 differs
+  const v1 = createHash("sha256")
+    .update("sonnet")
+    .update(msgsBase[0].role)
+    .update(msgsBase[0].content)
+    .digest("hex");
+  const v2 = cacheHash("sonnet", msgsBase, { keyId: "anon" });
+  assert.notEqual(v1, v2);
+});
+
+test("D1: cacheHash is reproducible for same keyId (determinism)", () => {
+  const h1 = cacheHash("sonnet", msgsBase, { keyId: "key-xyz" });
+  const h2 = cacheHash("sonnet", msgsBase, { keyId: "key-xyz" });
+  assert.equal(h1, h2);
+});
+
+test("D2: hasCacheControl returns true for top-level cache_control on message", () => {
+  const msgs = [{ role: "user", cache_control: { type: "ephemeral" }, content: "hello" }];
+  assert.equal(hasCacheControl(msgs), true);
+});
+
+test("D2: hasCacheControl returns true for nested cache_control in content array", () => {
+  const msgs = [{ role: "user", content: [{ type: "text", text: "x", cache_control: { type: "ephemeral" } }] }];
+  assert.equal(hasCacheControl(msgs), true);
+});
+
+test("D2: hasCacheControl returns false for plain string content", () => {
+  const msgs = [{ role: "user", content: "plain string" }];
+  assert.equal(hasCacheControl(msgs), false);
+});
+
+test("D2: hasCacheControl returns false for content array without cache_control", () => {
+  const msgs = [{ role: "user", content: [{ type: "text", text: "x" }] }];
+  assert.equal(hasCacheControl(msgs), false);
+});
+
+test("D2: hasCacheControl handles null/empty input gracefully", () => {
+  assert.equal(hasCacheControl(null), false);
+  assert.equal(hasCacheControl([]), false);
+  assert.equal(hasCacheControl([null, undefined]), false);
+});
+
+// D3: chunked stream replay — verify the logic by simulating what server.mjs does
+test("D3: 160-char cached response produces 2 chunks at 80 codepoints/chunk", () => {
+  const content = "a".repeat(160);
+  const CACHE_REPLAY_CHUNK_SIZE = 80;
+  const codepoints = Array.from(content);
+  const chunks = [];
+  for (let i = 0; i < codepoints.length; i += CACHE_REPLAY_CHUNK_SIZE) {
+    chunks.push(codepoints.slice(i, i + CACHE_REPLAY_CHUNK_SIZE).join(""));
+  }
+  assert.equal(chunks.length, 2);
+  assert.equal(chunks[0].length, 80);
+  assert.equal(chunks[1].length, 80);
+});
+
+test("D3: chunked replay uses Array.from — multibyte codepoints stay intact", () => {
+  // Each Chinese character is 1 codepoint but 3 UTF-8 bytes
+  const chinese = "你好世界".repeat(25); // 100 codepoints
+  const CACHE_REPLAY_CHUNK_SIZE = 80;
+  const codepoints = Array.from(chinese);
+  const chunks = [];
+  for (let i = 0; i < codepoints.length; i += CACHE_REPLAY_CHUNK_SIZE) {
+    chunks.push(codepoints.slice(i, i + CACHE_REPLAY_CHUNK_SIZE).join(""));
+  }
+  assert.equal(chunks.length, 2);
+  assert.equal(Array.from(chunks[0]).length, 80);
+  assert.equal(Array.from(chunks[1]).length, 20);
+  // Verify each character is a complete codepoint (no mojibake)
+  for (const chunk of chunks) {
+    for (const cp of Array.from(chunk)) {
+      assert.equal(cp.length <= 2, true); // surrogate pairs are length 2, single chars length 1
+    }
+  }
+});
+
+// ── PR-B Singleflight tests (async) ──
+async function asyncTest(name, fn) {
+  try {
+    await fn();
+    passed++;
+    console.log(`  ✓ ${name}`);
+  } catch (e) {
+    failed++;
+    console.log(`  ✗ ${name}: ${e.message}`);
+  }
+}
+
+async function runSingleflightTests() {
+  console.log("\nPR-B Singleflight:");
+
+  // 1. Basic dedup: 10 concurrent calls with same hash execute fn only once.
+  await asyncTest("basic dedup: 10 concurrent callers execute fn only once", async () => {
+    let callCount = 0;
+    const fn = () => new Promise(resolve => {
+      callCount++;
+      setTimeout(() => resolve("result-A"), 20);
+    });
+    const results = await Promise.all(Array.from({ length: 10 }, () => singleflight("sf-dedup-1", fn)));
+    assert.equal(callCount, 1, `fn called ${callCount} times, expected 1`);
+    assert.ok(results.every(r => r === "result-A"), "all 10 callers should receive the same return value");
+  });
+
+  // 2. Failure fan-out: all followers reject when leader rejects.
+  await asyncTest("failure fan-out: all followers reject with leader error", async () => {
+    let callCount = 0;
+    const fn = () => new Promise((_, reject) => {
+      callCount++;
+      setTimeout(() => reject(new Error("upstream-fail")), 20);
+    });
+    const promises = Array.from({ length: 10 }, () => singleflight("sf-fail-1", fn));
+    const results = await Promise.allSettled(promises);
+    assert.equal(callCount, 1, `fn called ${callCount} times, expected 1`);
+    assert.ok(results.every(r => r.status === "rejected"), "all 10 should be rejected");
+    assert.ok(results.every(r => r.reason?.message === "upstream-fail"), "all should share the same error message");
+  });
+
+  // 3a. Map cleanup after success: inflight count returns to 0 after promise resolves.
+  await asyncTest("map cleanup after success: inflight=0 after promise settles", async () => {
+    const fn = () => new Promise(resolve => setTimeout(() => resolve("done"), 10));
+    await singleflight("sf-cleanup-ok", fn);
+    const stats = getInflightStats();
+    assert.equal(stats.inflight, 0, `expected inflight=0 after settlement, got ${stats.inflight}`);
+  });
+
+  // 3b. Map cleanup after failure: inflight count returns to 0 after promise rejects.
+  await asyncTest("map cleanup after failure: inflight=0 after promise rejects", async () => {
+    const fn = () => new Promise((_, reject) => setTimeout(() => reject(new Error("fail")), 10));
+    try { await singleflight("sf-cleanup-fail", fn); } catch {}
+    const stats = getInflightStats();
+    assert.equal(stats.inflight, 0, `expected inflight=0 after rejection, got ${stats.inflight}`);
+  });
+
+  // 4. Different hashes don't share: two parallel calls with distinct hashes both execute.
+  await asyncTest("different hashes do not share a singleflight entry", async () => {
+    let countA = 0;
+    let countB = 0;
+    const fnA = () => new Promise(resolve => { countA++; setTimeout(() => resolve("A"), 20); });
+    const fnB = () => new Promise(resolve => { countB++; setTimeout(() => resolve("B"), 20); });
+    const [rA, rB] = await Promise.all([singleflight("sf-hash-A", fnA), singleflight("sf-hash-B", fnB)]);
+    assert.equal(countA, 1);
+    assert.equal(countB, 1);
+    assert.equal(rA, "A");
+    assert.equal(rB, "B");
+  });
+
+  // 5. getInflightStats shape: returns { inflight: number, requesters: number }.
+  await asyncTest("getInflightStats returns correct shape", async () => {
+    // Verify shape against a settled state (inflight=0 is still the right shape).
+    const stats = getInflightStats();
+    assert.equal(typeof stats.inflight, "number", "inflight should be a number");
+    assert.equal(typeof stats.requesters, "number", "requesters should be a number");
+    // Also verify live counts: start a pending fn, check inflight>0, then resolve.
+    const { promise: blocker, resolve: resolveBlocker } = Promise.withResolvers();
+    const fn = () => blocker;
+    const p = singleflight("sf-stats-shape", fn);
+    const liveStats = getInflightStats();
+    assert.ok(liveStats.inflight >= 1, `expected inflight>=1, got ${liveStats.inflight}`);
+    resolveBlocker("ok");
+    await p;
+  });
+
+  // 6. Sequential calls don't share: singleflight is for concurrent dedup only.
+  await asyncTest("sequential calls with same hash each execute fn independently", async () => {
+    let callCount = 0;
+    const fn = () => new Promise(resolve => { callCount++; setTimeout(() => resolve(callCount), 10); });
+    const r1 = await singleflight("sf-sequential", fn);
+    const r2 = await singleflight("sf-sequential", fn);
+    assert.equal(callCount, 2, `fn should have been called twice, got ${callCount}`);
+    assert.equal(r1, 1);
+    assert.equal(r2, 2);
+  });
+}
+
+await runSingleflightTests();
+
+// ── Plist Env Merge Tests ──
+import { mergePlistEnv, mergeSystemdEnv } from "./scripts/lib/plist-merge.mjs";
+
+console.log("\nPlist env merge:");
+
+const SAMPLE_TEMPLATE_PLIST = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>dev.ocp.proxy</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>CLAUDE_PROXY_PORT</key>
+    <string>3478</string>
+    <key>CLAUDE_BIND</key>
+    <string>127.0.0.1</string>
+    <key>CLAUDE_AUTH_MODE</key>
+    <string>multi</string>
+  </dict>
+</dict>
+</plist>`;
+
+const SAMPLE_EXISTING_PLIST = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>dev.ocp.proxy</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>CLAUDE_PROXY_PORT</key>
+    <string>3456</string>
+    <key>CLAUDE_BIND</key>
+    <string>127.0.0.1</string>
+    <key>CLAUDE_AUTH_MODE</key>
+    <string>none</string>
+    <key>CLAUDE_HEARTBEAT_INTERVAL</key>
+    <string>2000</string>
+    <key>CLAUDE_CACHE_TTL</key>
+    <string>600</string>
+  </dict>
+</dict>
+</plist>`;
+
+test("mergePlistEnv preserves unknown user keys", () => {
+  const merged = mergePlistEnv(SAMPLE_EXISTING_PLIST, SAMPLE_TEMPLATE_PLIST);
+  assert.match(merged, /<key>CLAUDE_HEARTBEAT_INTERVAL<\/key>\s*<string>2000<\/string>/);
+  assert.match(merged, /<key>CLAUDE_CACHE_TTL<\/key>\s*<string>600<\/string>/);
+});
+
+test("mergePlistEnv overrides known template keys", () => {
+  const merged = mergePlistEnv(SAMPLE_EXISTING_PLIST, SAMPLE_TEMPLATE_PLIST);
+  assert.match(merged, /<key>CLAUDE_PROXY_PORT<\/key>\s*<string>3478<\/string>/);
+  assert.match(merged, /<key>CLAUDE_AUTH_MODE<\/key>\s*<string>multi<\/string>/);
+});
+
+test("mergePlistEnv first-install returns template unchanged when existing is null", () => {
+  const merged = mergePlistEnv(null, SAMPLE_TEMPLATE_PLIST);
+  assert.equal(merged, SAMPLE_TEMPLATE_PLIST);
+});
+
+test("mergePlistEnv first-install returns template unchanged when existing is empty", () => {
+  const merged = mergePlistEnv("", SAMPLE_TEMPLATE_PLIST);
+  assert.equal(merged, SAMPLE_TEMPLATE_PLIST);
+});
+
+const SAMPLE_TEMPLATE_SYSTEMD = `[Unit]
+Description=OCP — Open Claude Proxy
+After=network.target
+
+[Service]
+ExecStart=/usr/bin/node /home/u/ocp/server.mjs
+Environment=CLAUDE_PROXY_PORT=3478
+Environment=CLAUDE_BIND=127.0.0.1
+Environment=CLAUDE_AUTH_MODE=multi
+Restart=always
+`;
+
+const SAMPLE_EXISTING_SYSTEMD = `[Unit]
+Description=OCP — Open Claude Proxy
+After=network.target
+
+[Service]
+ExecStart=/usr/bin/node /home/u/ocp/server.mjs
+Environment=CLAUDE_PROXY_PORT=3456
+Environment=CLAUDE_BIND=127.0.0.1
+Environment=CLAUDE_AUTH_MODE=none
+Environment=CLAUDE_HEARTBEAT_INTERVAL=2000
+Environment=CLAUDE_CACHE_TTL=600
+Restart=always
+`;
+
+test("mergeSystemdEnv preserves unknown user Environment lines", () => {
+  const merged = mergeSystemdEnv(SAMPLE_EXISTING_SYSTEMD, SAMPLE_TEMPLATE_SYSTEMD);
+  assert.match(merged, /Environment=CLAUDE_HEARTBEAT_INTERVAL=2000/);
+  assert.match(merged, /Environment=CLAUDE_CACHE_TTL=600/);
+});
+
+test("mergeSystemdEnv overrides known template keys", () => {
+  const merged = mergeSystemdEnv(SAMPLE_EXISTING_SYSTEMD, SAMPLE_TEMPLATE_SYSTEMD);
+  assert.match(merged, /Environment=CLAUDE_PROXY_PORT=3478/);
+  assert.match(merged, /Environment=CLAUDE_AUTH_MODE=multi/);
+});
+
+test("mergeSystemdEnv first-install returns template unchanged", () => {
+  assert.equal(mergeSystemdEnv(null, SAMPLE_TEMPLATE_SYSTEMD), SAMPLE_TEMPLATE_SYSTEMD);
+  assert.equal(mergeSystemdEnv("", SAMPLE_TEMPLATE_SYSTEMD), SAMPLE_TEMPLATE_SYSTEMD);
+});
+
+test("mergePlistEnv is idempotent", () => {
+  const r1 = mergePlistEnv(SAMPLE_EXISTING_PLIST, SAMPLE_TEMPLATE_PLIST);
+  assert.equal(mergePlistEnv(r1, SAMPLE_TEMPLATE_PLIST), r1);
+});
+
+test("mergeSystemdEnv is idempotent", () => {
+  const r1 = mergeSystemdEnv(SAMPLE_EXISTING_SYSTEMD, SAMPLE_TEMPLATE_SYSTEMD);
+  assert.equal(mergeSystemdEnv(r1, SAMPLE_TEMPLATE_SYSTEMD), r1);
+});
+
+// ── Doctor JSON Contract Tests ──
+import { runDoctor } from "./scripts/doctor.mjs";
+
+console.log("\nDoctor:");
+
+test("doctor --json shape: required top-level keys", async () => {
+  const result = await runDoctor({ skipNetwork: true, mockVersion: "v3.10.0", mockLatest: "v3.14.0" });
+  for (const k of ["schema_version", "ready_to_upgrade", "current_version", "latest_version",
+                   "from_version_supported", "fail_count", "warn_count", "checks", "next_action"]) {
+    assert.ok(k in result, `missing key: ${k}`);
+  }
+  assert.equal(result.schema_version, "1");
+});
+
+test("doctor detects from-version < v3.4.0 → fresh_install", async () => {
+  const result = await runDoctor({ skipNetwork: true, mockVersion: "v3.2.0", mockLatest: "v3.14.0" });
+  assert.equal(result.from_version_supported, false);
+  assert.equal(result.next_action.kind, "fresh_install");
+  assert.ok(Array.isArray(result.next_action.ai_executable));
+  assert.ok(result.next_action.ai_executable.length > 0);
+});
+
+test("doctor next_action.kind enum is one of allowed values", async () => {
+  const result = await runDoctor({ skipNetwork: true, mockVersion: "v3.10.0", mockLatest: "v3.14.0" });
+  const ALLOWED = ["noop", "update", "upgrade", "fresh_install", "fix_oauth", "fix_service"];
+  assert.ok(ALLOWED.includes(result.next_action.kind), `kind=${result.next_action.kind} not in enum`);
+});
+
+test("doctor noop when current==latest", async () => {
+  const result = await runDoctor({ skipNetwork: true, mockVersion: "v3.14.0", mockLatest: "v3.14.0" });
+  assert.equal(result.next_action.kind, "noop");
+  assert.equal(result.ready_to_upgrade, true);
+});
+
+test("doctor patch-bump same minor → update kind", async () => {
+  const result = await runDoctor({ skipNetwork: true, mockVersion: "v3.14.0", mockLatest: "v3.14.1" });
+  assert.equal(result.next_action.kind, "update");
+});
+
+test("doctor cross-minor → upgrade kind", async () => {
+  const result = await runDoctor({ skipNetwork: true, mockVersion: "v3.10.0", mockLatest: "v3.14.0" });
+  assert.equal(result.next_action.kind, "upgrade");
+});
+
+test("doctor OAuth FAIL → fix_oauth kind", async () => {
+  const result = await runDoctor({
+    skipNetwork: false,
+    mockVersion: "v3.10.0",
+    mockLatest: "v3.14.0",
+    mockHealth: { status: 200, body: { auth: { ok: false, message: "ENOEXEC" } } }
+  });
+  assert.equal(result.next_action.kind, "fix_oauth");
+  assert.ok(result.next_action.ai_executable.some(c => c.includes("install.cjs")));
+});
+
+test("doctor service down → fix_service kind", async () => {
+  const result = await runDoctor({
+    skipNetwork: false,
+    mockVersion: "v3.10.0",
+    mockLatest: "v3.14.0",
+    mockHealth: { error: "ECONNREFUSED" }
+  });
+  assert.equal(result.next_action.kind, "fix_service");
+});
+
+test("doctor unparseable version → fresh_install", async () => {
+  const result = await runDoctor({ skipNetwork: true, mockVersion: "garbage", mockLatest: "v3.14.0" });
+  assert.equal(result.from_version_supported, false);
+  assert.equal(result.next_action.kind, "fresh_install");
+});
+
+test("doctor empty health body → fix_service (not fix_oauth)", async () => {
+  const result = await runDoctor({
+    skipNetwork: false,
+    mockVersion: "v3.10.0",
+    mockLatest: "v3.14.0",
+    mockHealth: { status: 200, body: null }
+  });
+  assert.equal(result.next_action.kind, "fix_service");
+});
+
+test("doctor falls back to currentVersion when origin/main unreachable (no stale latest)", async () => {
+  // Use a non-existent ocpDir so git command fails; without the fix this would still
+  // hard-code v3.14.0 as latest and recommend a downgrade for a future v3.15.0+ user.
+  const result = await runDoctor({
+    skipNetwork: true,
+    mockVersion: "v3.15.0",
+    ocpDir: "/nonexistent-ocp-dir-for-test"
+  });
+  assert.equal(result.latest_version, "v3.15.0");
+  assert.equal(result.next_action.kind, "noop");
+});
+
+// ── Upgrade Tests ──
+import { runUpgrade } from "./scripts/upgrade.mjs";
+
+console.log("\nUpgrade:");
+
+test("upgrade --dry-run prints plan, no side effects", async () => {
+  const result = await runUpgrade({
+    dryRun: true,
+    yes: true,
+    mockDoctor: { ready_to_upgrade: true, next_action: { kind: "upgrade" }, current_version: "v3.10.0", latest_version: "v3.14.0" }
+  });
+  assert.equal(result.executed, false);
+  assert.ok(result.plan.length > 0);
+  assert.ok(result.plan.some(line => line.toLowerCase().includes("snapshot")));
+});
+
+test("upgrade noop returns early when current==latest", async () => {
+  const result = await runUpgrade({
+    yes: true,
+    mockDoctor: { ready_to_upgrade: true, next_action: { kind: "noop" }, current_version: "v3.14.0", latest_version: "v3.14.0" }
+  });
+  assert.equal(result.path, "noop");
+  assert.equal(result.executed, true);
+  assert.equal(result.changed, false);
+});
+
+test("upgrade aborts on doctor FAIL", async () => {
+  await assert.rejects(async () => {
+    await runUpgrade({
+      yes: true,
+      mockDoctor: { ready_to_upgrade: false, fail_count: 1, next_action: { kind: "fix_oauth" } }
+    });
+  }, /doctor FAIL/);
+});
+
+test("upgrade full path executes 5 phases", async () => {
+  const result = await runUpgrade({
+    yes: true,
+    dryRun: false,
+    mockExec: true,
+    mockDoctor: { ready_to_upgrade: true, next_action: { kind: "upgrade" },
+                  current_version: "v3.10.0", latest_version: "v3.14.0" }
+  });
+  assert.equal(result.path, "upgrade");
+  // Plan asks for 6 phases by name; verify each appears as a phase entry
+  const phaseNames = result.phases.map(p => p.name);
+  for (const expected of ["pre-flight", "snapshot", "fetch+install", "reconfigure", "restart", "post-flight"]) {
+    assert.ok(phaseNames.includes(expected), `missing phase: ${expected}; got ${phaseNames.join(",")}`);
+  }
+});
+
+// ── Snapshot Tests ──
+import { writeSnapshot, readSnapshot, listSnapshots, gcSnapshots } from "./scripts/lib/snapshot.mjs";
+import { mkdtempSync, rmSync, mkdirSync as tMkdirSync, writeFileSync as testWriteFile, existsSync as testExistsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join as testJoin } from "node:path";
+
+console.log("\nSnapshot:");
+
+test("writeSnapshot creates dir + manifest files", () => {
+  const root = mkdtempSync(testJoin(tmpdir(), "ocp-snap-test-"));
+  const dotOcp = testJoin(root, ".ocp");
+  tMkdirSync(dotOcp, { recursive: true });
+  testWriteFile(testJoin(dotOcp, "ocp.db"), "fake-sqlite-bytes");
+
+  const path = writeSnapshot({
+    homeDir: root,
+    fromCommit: "abc1234",
+    fromVersion: "v3.10.0",
+    toVersion: "v3.14.0",
+    extraFiles: []
+  });
+  const m = readSnapshot(path);
+  assert.equal(m.fromCommit, "abc1234");
+  assert.equal(m.fromVersion, "v3.10.0");
+  rmSync(root, { recursive: true, force: true });
+});
+
+test("listSnapshots returns sorted by ISO timestamp", () => {
+  const root = mkdtempSync(testJoin(tmpdir(), "ocp-snap-list-"));
+  const dotOcp = testJoin(root, ".ocp");
+  tMkdirSync(dotOcp, { recursive: true });
+  for (const ts of ["2026-05-01T10:00:00Z", "2026-05-02T10:00:00Z", "2026-05-03T10:00:00Z"]) {
+    tMkdirSync(testJoin(dotOcp, `upgrade-snapshot-${ts}`));
+  }
+  const list = listSnapshots(root);
+  assert.equal(list.length, 3);
+  assert.ok(list[0].path.includes("2026-05-01"));
+  assert.ok(list[2].path.includes("2026-05-03"));
+  rmSync(root, { recursive: true, force: true });
+});
+
+test("upgrade error after snapshot carries snapshotPath + hint", async () => {
+  // Use mockExec=true so no real commands are run.
+  // Verify the success path returns a snapshotPath (Fix B regression guard).
+  const result = await runUpgrade({
+    yes: true,
+    dryRun: false,
+    mockExec: true,
+    mockDoctor: { ready_to_upgrade: true, next_action: { kind: "upgrade" },
+                  current_version: "v3.10.0", latest_version: "v3.14.0" }
+  });
+  assert.ok(result.snapshotPath, "successful upgrade returns snapshotPath");
+  assert.equal(result.path, "upgrade");
+  assert.equal(result.executed, true);
+});
+
+test("upgrade fresh_install requires --yes for non-interactive", async () => {
+  await assert.rejects(async () => {
+    await runUpgrade({
+      yes: false,
+      mockExec: true,
+      mockDoctor: { ready_to_upgrade: false, from_version_supported: false,
+                    next_action: { kind: "fresh_install", ai_executable: ["echo would-rm-rf"] },
+                    current_version: "v3.2.0", latest_version: "v3.14.0" }
+    });
+  }, /requires --yes/);
+});
+
+test("upgrade fresh_install with --yes runs ai_executable", async () => {
+  const result = await runUpgrade({
+    yes: true,
+    mockExec: true,
+    mockDoctor: { ready_to_upgrade: false, from_version_supported: false,
+                  next_action: { kind: "fresh_install",
+                                 ai_executable: ["echo step-1", "echo step-2", "echo step-3"] },
+                  current_version: "v3.2.0", latest_version: "v3.14.0" }
+  });
+  assert.equal(result.path, "fresh_install");
+  assert.equal(result.steps.length, 3);
+});
+
+test("rollback --list returns snapshots", async () => {
+  const result = await runUpgrade({
+    rollback: true,
+    list: true,
+    mockSnapshots: [
+      { name: "upgrade-snapshot-2026-05-01T10:00:00Z", path: "/tmp/snap-1" },
+      { name: "upgrade-snapshot-2026-05-02T10:00:00Z", path: "/tmp/snap-2" }
+    ]
+  });
+  assert.equal(result.path, "rollback-list");
+  assert.equal(result.snapshots.length, 2);
+});
+
+test("rollback with no snapshots fails clearly", async () => {
+  await assert.rejects(async () => {
+    await runUpgrade({ rollback: true, dryRun: true, mockSnapshots: [] });
+  }, /no upgrade snapshots/);
+});
+
+test("rollback --dry-run produces a plan without mutation", async () => {
+  const result = await runUpgrade({
+    rollback: true,
+    dryRun: true,
+    mockSnapshots: [{ name: "upgrade-snapshot-2026-05-11T08:30:00Z", path: "/tmp/snap-x" }],
+    mockSnapshotMeta: { fromCommit: "abc1234", fromVersion: "v3.10.0", toVersion: "v3.14.0", path: "/tmp/snap-x" }
+  });
+  assert.equal(result.path, "rollback-dry-run");
+  assert.equal(result.executed, false);
+  assert.ok(result.plan.length > 0);
+});
+
+test("rollback latest snapshot restores files (mockExec)", async () => {
+  const result = await runUpgrade({
+    rollback: true,
+    yes: true,
+    mockExec: true,
+    mockSnapshots: [{ name: "upgrade-snapshot-2026-05-11T08:30:00Z", path: "/tmp/snap-x" }],
+    mockSnapshotMeta: { fromCommit: "abc1234", fromVersion: "v3.10.0", toVersion: "v3.14.0", path: "/tmp/snap-x" }
+  });
+  assert.equal(result.path, "rollback");
+  assert.equal(result.executed, true);
+  assert.ok(result.phases.some(p => p.name === "git-checkout"));
+});
+
+test("gcSnapshots keeps last N regardless of age", () => {
+  const root = mkdtempSync(testJoin(tmpdir(), "ocp-gc-test-"));
+  const dotOcp = testJoin(root, ".ocp");
+  tMkdirSync(dotOcp, { recursive: true });
+  for (const ts of ["2026-04-01T10:00:00Z", "2026-04-15T10:00:00Z", "2026-04-30T10:00:00Z", "2026-05-01T10:00:00Z", "2026-05-10T10:00:00Z"]) {
+    tMkdirSync(testJoin(dotOcp, `upgrade-snapshot-${ts}`));
+  }
+  const result = gcSnapshots(root, { keepCount: 3, keepDays: 0, now: new Date("2026-05-11T00:00:00Z") });
+  assert.equal(result.kept.length, 3);
+  assert.equal(result.removed.length, 2);
+  assert.ok(result.kept[0].name.includes("2026-04-30"));
+  assert.ok(result.kept[2].name.includes("2026-05-10"));
+  rmSync(root, { recursive: true, force: true });
+});
+
+test("gcSnapshots keeps snapshots newer than keepDays regardless of count", () => {
+  const root = mkdtempSync(testJoin(tmpdir(), "ocp-gc-days-"));
+  const dotOcp = testJoin(root, ".ocp");
+  tMkdirSync(dotOcp, { recursive: true });
+  for (const ts of ["2026-04-01T10:00:00Z", "2026-04-15T10:00:00Z", "2026-04-30T10:00:00Z", "2026-05-01T10:00:00Z", "2026-05-10T10:00:00Z"]) {
+    tMkdirSync(testJoin(dotOcp, `upgrade-snapshot-${ts}`));
+  }
+  // keepCount=1 but keepDays=15 means anything from after 2026-04-26 is kept too
+  const result = gcSnapshots(root, { keepCount: 1, keepDays: 15, now: new Date("2026-05-11T00:00:00Z") });
+  // Kept: 2026-04-30 (within 15 days), 2026-05-01 (within 15 days), 2026-05-10 (within 15 days)
+  assert.ok(result.kept.length >= 3);
+  // Removed: 2026-04-01, 2026-04-15
+  assert.ok(result.removed.some(s => s.name.includes("2026-04-01")));
+});
+
+test("gcSnapshots never deletes the most recent snapshot", () => {
+  const root = mkdtempSync(testJoin(tmpdir(), "ocp-gc-recent-"));
+  const dotOcp = testJoin(root, ".ocp");
+  tMkdirSync(dotOcp, { recursive: true });
+  tMkdirSync(testJoin(dotOcp, "upgrade-snapshot-2026-01-01T10:00:00Z"));
+  // Even with keepCount=0 and keepDays=0, the most recent must survive
+  const result = gcSnapshots(root, { keepCount: 0, keepDays: 0, now: new Date("2026-05-11T00:00:00Z") });
+  assert.equal(result.kept.length, 1);
+  assert.equal(result.removed.length, 0);
+  rmSync(root, { recursive: true, force: true });
+});
+
+test("gcSnapshots --dry-run reports plan without deleting", () => {
+  const root = mkdtempSync(testJoin(tmpdir(), "ocp-gc-dryrun-"));
+  const dotOcp = testJoin(root, ".ocp");
+  tMkdirSync(dotOcp, { recursive: true });
+  for (const ts of ["2026-04-01T10:00:00Z", "2026-04-15T10:00:00Z", "2026-05-10T10:00:00Z"]) {
+    tMkdirSync(testJoin(dotOcp, `upgrade-snapshot-${ts}`));
+  }
+  const result = gcSnapshots(root, { keepCount: 1, keepDays: 0, dryRun: true, now: new Date("2026-05-11T00:00:00Z") });
+  assert.equal(result.dryRun, true);
+  assert.equal(result.removed.length, 2);
+  // Files still exist
+  assert.ok(testExistsSync(testJoin(dotOcp, "upgrade-snapshot-2026-04-01T10:00:00Z")));
+  rmSync(root, { recursive: true, force: true });
+});
+
+// ── Doctor --check oauth fast path tests ──
+console.log("\nDoctor --check oauth:");
+
+await asyncTest("doctor --check oauth runs only oauth check (skips version/from-version)", async () => {
+  const result = await runDoctor({
+    checkOnly: "oauth",
+    mockVersion: "v3.10.0",
+    mockLatest: "v3.14.0",
+    mockHealth: { status: 200, body: { auth: { ok: true, message: "authenticated" } } }
+  });
+  // Should still produce a valid result object
+  assert.equal(result.schema_version, "1");
+  // checks[] should only contain oauth_ok (no current_version, no from_version_supported)
+  const ids = result.checks.map(c => c.id);
+  assert.deepEqual(ids, ["oauth_ok"]);
+  assert.equal(result.next_action.kind, "noop");
+});
+
+await asyncTest("doctor --check oauth + OAuth FAIL → fix_oauth", async () => {
+  const result = await runDoctor({
+    checkOnly: "oauth",
+    mockHealth: { status: 200, body: { auth: { ok: false, message: "ENOEXEC" } } }
+  });
+  const ids = result.checks.map(c => c.id);
+  assert.deepEqual(ids, ["oauth_ok"]);
+  assert.equal(result.next_action.kind, "fix_oauth");
+  assert.equal(result.fail_count, 1);
+});
+
+await asyncTest("doctor --check oauth + service down → fix_service", async () => {
+  const result = await runDoctor({
+    checkOnly: "oauth",
+    mockHealth: { error: "ECONNREFUSED" }
+  });
+  const ids = result.checks.map(c => c.id);
+  assert.deepEqual(ids, ["oauth_ok"]);
+  assert.equal(result.next_action.kind, "fix_service");
+  assert.equal(result.fail_count, 1);
+});
+
+await asyncTest("doctor --check oauth + 200 with null body → fix_service", async () => {
+  const result = await runDoctor({
+    checkOnly: "oauth",
+    mockHealth: { status: 200, body: null }
+  });
+  const ids = result.checks.map(c => c.id);
+  assert.deepEqual(ids, ["oauth_ok"]);
+  assert.equal(result.next_action.kind, "fix_service");
+  assert.equal(result.fail_count, 1);
+});
+
+// ── Cleanup ──
+closeDb();
+
+console.log(`\n=== Results: ${passed} passed, ${failed} failed ===\n`);
+process.exit(failed > 0 ? 1 : 0);

uninstall.mjs

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 /**
- * openclaw-claude-proxy uninstaller
+ * OCP (Open Claude Proxy) uninstaller
  *
  * Stops and removes the launchd (macOS) or systemd (Linux) auto-start entry.
+ * Handles both legacy (ai.openclaw.proxy / openclaw-proxy) and current
+ * (dev.ocp.proxy / ocp-proxy) service names.
+ *
  * Run: node uninstall.mjs
  */
 import { existsSync, unlinkSync } from "node:fs";
@@ -15,43 +18,52 @@ const HOME = homedir();
 function log(msg) { console.log(`  ✓ ${msg}`); }
 function warn(msg) { console.log(`  ⚠ ${msg}`); }
 
-console.log("\n🗑  Uninstalling openclaw-claude-proxy auto-start...\n");
+console.log("\n🗑  Uninstalling OCP auto-start...\n");
 
 const platform = process.platform;
 
 if (platform === "darwin") {
-  const plistPath = join(HOME, "Library", "LaunchAgents", "ai.openclaw.proxy.plist");
-
+  // Remove current service
+  const plistPath = join(HOME, "Library", "LaunchAgents", "dev.ocp.proxy.plist");
   if (existsSync(plistPath)) {
-    try {
-      execSync(`launchctl unload "${plistPath}" 2>/dev/null`);
-      log("launchd service stopped and unloaded");
-    } catch {
-      warn("launchctl unload failed (service may not have been running)");
-    }
+    try { execSync(`launchctl bootout gui/$(id -u) "${plistPath}" 2>/dev/null`); } catch { /* ignore */ }
     unlinkSync(plistPath);
-    log(`Plist removed: ${plistPath}`);
-  } else {
-    warn(`Plist not found: ${plistPath}`);
+    log(`Removed: ${plistPath}`);
+  }
+
+  // Remove legacy service
+  const legacyPath = join(HOME, "Library", "LaunchAgents", "ai.openclaw.proxy.plist");
+  if (existsSync(legacyPath)) {
+    try { execSync(`launchctl bootout gui/$(id -u) "${legacyPath}" 2>/dev/null`); } catch { /* ignore */ }
+    unlinkSync(legacyPath);
+    log(`Removed legacy: ${legacyPath}`);
+  }
+
+  if (!existsSync(plistPath) && !existsSync(legacyPath)) {
+    warn("No plist found (service may not have been installed)");
   }
 
 } else if (platform === "linux") {
-  const servicePath = join(HOME, ".config", "systemd", "user", "openclaw-proxy.service");
-
-  try { execSync(`systemctl --user stop openclaw-proxy 2>/dev/null`); } catch { /* ignore */ }
-  log("systemd service stopped");
-
-  try { execSync(`systemctl --user disable openclaw-proxy 2>/dev/null`); } catch { /* ignore */ }
-  log("systemd service disabled");
-
+  // Remove current service
+  const servicePath = join(HOME, ".config", "systemd", "user", "ocp-proxy.service");
+  try { execSync(`systemctl --user stop ocp-proxy 2>/dev/null`); } catch { /* ignore */ }
+  try { execSync(`systemctl --user disable ocp-proxy 2>/dev/null`); } catch { /* ignore */ }
   if (existsSync(servicePath)) {
     unlinkSync(servicePath);
-    log(`Service file removed: ${servicePath}`);
-  } else {
-    warn(`Service file not found: ${servicePath}`);
+    log(`Removed: ${servicePath}`);
+  }
+
+  // Remove legacy service
+  const legacyPath = join(HOME, ".config", "systemd", "user", "openclaw-proxy.service");
+  try { execSync(`systemctl --user stop openclaw-proxy 2>/dev/null`); } catch { /* ignore */ }
+  try { execSync(`systemctl --user disable openclaw-proxy 2>/dev/null`); } catch { /* ignore */ }
+  if (existsSync(legacyPath)) {
+    unlinkSync(legacyPath);
+    log(`Removed legacy: ${legacyPath}`);
   }
 
   try { execSync(`systemctl --user daemon-reload`); } catch { /* ignore */ }
+  log("systemd daemon reloaded");
 
 } else {
   warn(`Auto-start not supported on ${platform} — nothing to remove`);