diff --git a/AGENTS.md b/AGENTS.md index 93f751e..008feb4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,7 +36,9 @@ Runtime: Node.js (ESM, `.mjs` throughout). No build step. No bundler. `server.mj - `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. +- `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). --- @@ -66,7 +68,7 @@ A fresh session picking up OCP work should read, in order: 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 spec under `docs/superpowers/specs/*/tasks.md` (if present). +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. diff --git a/README.md b/README.md index 464f1c6..292283d 100644 --- a/README.md +++ b/README.md @@ -55,9 +55,11 @@ Any tool that accepts `OPENAI_BASE_URL` works with OCP: | **OpenCode** | `OPENAI_BASE_URL=http://127.0.0.1:3456/v1` | | **Aider** | `aider --openai-api-base http://127.0.0.1:3456/v1` | | **Continue.dev** | config.json → `apiBase: "http://127.0.0.1:3456/v1"` | -| **OpenClaw** | `setup.mjs` auto-configures | +| **OpenClaw** [^openclaw] | `setup.mjs` auto-configures | | **Any OpenAI client** | Set base URL to `http://127.0.0.1:3456/v1` | +[^openclaw]: **OpenClaw** is an IDE-agnostic AI coding agent (sibling project to OCP). When OCP runs on the same machine, OpenClaw can use it as a local provider — see `scripts/sync-openclaw.mjs` and ADR 0004. + ## Installation OCP has two roles: **Server** (runs the proxy, needs Claude CLI) and **Client** (connects to a server, zero dependencies). @@ -131,6 +133,17 @@ curl http://127.0.0.1:3456/v1/models --- +### Uninstall + +```bash +# From the cloned repo +node uninstall.mjs +``` + +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. Does not delete `~/.openclaw/`, `~/.ocp/`, or the cloned repo — remove those manually if desired. + +--- + ### Client Setup > Clients do **not** need to install Node.js, Claude CLI, or the OCP repo. Only `curl` and `python3` are required (pre-installed on most Linux/Mac systems). @@ -645,6 +658,26 @@ Heartbeats are inert SSE comment lines — conforming SSE clients ignore them. I OCP also sends `X-Accel-Buffering: no` on SSE responses so nginx-default proxy buffering does not hold heartbeats in an upstream buffer. +## Repository Layout + +Top-level files a contributor or operator may need to know: + +| Path | Role | +|------|------| +| `server.mjs` | The proxy itself; every request path lives here. Governed by `ALIGNMENT.md`. | +| `setup.mjs` | First-time installer — verifies Claude CLI, patches OpenClaw config, installs auto-start. | +| `uninstall.mjs` | Reverses the launchd / systemd auto-start install. | +| `keys.mjs` | API-key management module (multi-mode auth: create/list/revoke, quotas, usage tracking). | +| `models.json` | Single source of truth for model IDs, aliases, context windows. See ADR 0003. | +| `ocp` / `ocp-connect` | User-facing CLI wrappers (server-side / client-side respectively). | +| `dashboard.html` | Static dashboard served from `/dashboard`. | +| `scripts/sync-openclaw.mjs` | Idempotent OpenClaw registry sync invoked by `ocp update`. See ADR 0004. | +| `.claude/skills/` | Project-specific Claude Code skills. | +| `ocp-plugin/` | OpenClaw gateway plugin (optional installation). | +| `docs/adr/` | Architecture Decision Records. Read these before proposing governance or SPOT changes — see [`docs/adr/README.md`](docs/adr/README.md). | +| `ALIGNMENT.md` | The constitution. Binding for any `server.mjs` change. | +| `AGENTS.md` / `CLAUDE.md` | Agent and Claude-Code-specific session instructions. | + ## Security - **Localhost by default** — binds to `127.0.0.1`; set `CLAUDE_BIND=0.0.0.0` to enable LAN access @@ -670,4 +703,4 @@ If you want to contribute: read `ALIGNMENT.md` first, search `cli.js` for the op ## License -MIT +MIT — see [`LICENSE`](LICENSE). diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..0f6cfc2 --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,37 @@ +# 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-.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. | + +## 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. diff --git a/docs/superpowers/plans/2026-04-10-lan-mode.md b/docs/superpowers/plans/shipped/2026-04-10-lan-mode.md similarity index 100% rename from docs/superpowers/plans/2026-04-10-lan-mode.md rename to docs/superpowers/plans/shipped/2026-04-10-lan-mode.md diff --git a/docs/superpowers/plans/2026-04-25-47-sse-heartbeat-plan.md b/docs/superpowers/plans/shipped/2026-04-25-47-sse-heartbeat-plan.md similarity index 100% rename from docs/superpowers/plans/2026-04-25-47-sse-heartbeat-plan.md rename to docs/superpowers/plans/shipped/2026-04-25-47-sse-heartbeat-plan.md diff --git a/specs/.gitkeep b/specs/.gitkeep deleted file mode 100644 index e69de29..0000000