mirror of
https://github.com/dtzp555-max/ocp.git
synced 2026-07-19 09:44:07 +00:00
docs: align README + governance docs with current state (uninstall, files, ADR index, ship-archive) (#59)
Multiple documentation polish items rolled into one PR (one layer: "docs alignment with current state"). ### README.md - **Uninstall section** added between Server Setup and Client Setup (was missing — `node uninstall.mjs` exists but went undocumented). - **OpenClaw definition** added as a footnote on first README mention (the architecture diagram and Supported Tools table both reference OpenClaw without ever defining it). - **Repository Layout section** added before Security — table of top-level files (server.mjs, setup.mjs, uninstall.mjs, keys.mjs, models.json, ocp/ocp-connect, dashboard.html, scripts/, .claude/skills/, ocp-plugin/, docs/adr/, ALIGNMENT.md, AGENTS.md, CLAUDE.md) so a new contributor knows what each file does. - **LICENSE link** added to the License section footer. ### docs/adr/README.md (new) - Index of the three published ADRs (0002, 0003, 0004) with a one-line description each. - Explains the `0001` placeholder (early internal proposal that was superseded; numbering deliberately starts at `0002`). - Guidance on when to write a new ADR vs. when a commit message suffices. ### Spec/plan housekeeping - `specs/.gitkeep` removed (the empty `specs/` placeholder confused the picture; canonical paths are `docs/superpowers/plans/` for active plans and `docs/superpowers/specs/` for long-lived design docs that other code references). - Shipped plans moved to `docs/superpowers/plans/shipped/`: - `2026-04-10-lan-mode.md` (shipped: README LAN mode section) - `2026-04-25-47-sse-heartbeat-plan.md` (shipped: v3.12.0 per CHANGELOG) - `2026-04-25-47-sse-heartbeat-design.md` left in `docs/superpowers/specs/` unchanged because both `server.mjs:565` and `CHANGELOG.md:7` link to that exact path; moving it would require a `server.mjs` edit, which needs `cli.js` citation per ALIGNMENT.md Rule 1. ### AGENTS.md - Updated "Key files to know" to add `docs/adr/README.md`, `docs/superpowers/plans/`, and `memory/constitution.md`. - Note explaining `memory/constitution.md` is spec-kit's standard location, distinct from `~/.cc-rules/memory/` and `ALIGNMENT.md`. - Updated "Handoff expectations" item 5 from `docs/superpowers/specs/*/tasks.md` (which never matched anything — there were no `tasks.md` files there) to `docs/superpowers/plans/` (excluding `shipped/`). ### Coordination with PR #53 PR #53 is open and adds "Why OCP?", "Comparison", and "Governance" sections to README. This PR deliberately avoids those areas — only edits the Supported Tools table footnote, inserts Uninstall before Client Setup, inserts Repository Layout before Security, and updates the License footer. No expected merge conflict. Refs: audit findings M6, M8, M9, M11, L2, L3, L6. Co-authored-by: dtzp555 <dtzp555@gmail.com>
This commit is contained in:
dtzp555-max
@@ -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.
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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-<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. |
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user