Repository navigation
docs: README maturity table, verified quick start, promote guide (PR 4 of REORG-PLAN) - #492
Conversation
- Add a per-path maturity table; status badge says preview. - Quick Start: pass the credential, add a verify and stop step and the mocactl installer; link the get-started chooser. - Move the Claude Code workflow promotion section to docs/guides/promote-claude-workflow.md (verbatim, with a lead note about mocactl promote) and leave a short summary. - Shrink the Legacy section to a pointer; replace the Phase 1/Z-table roadmap with a pointer to the milestone registry; replace the docs list with a table linking the docs map; list config-bundle and ibac-stub. - REORG-PLAN: record what PR 4 shipped and the remaining README length. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>
Rewrite docs/guides/promote-claude-workflow.md around mocactl promote (headless and the TUI /promote), with exit codes, session-fixed bundles, the byte budget and orchestrator dispatch. The older Redis-tunnel slash-command flow is reduced to a pointer. Update the README summary, features bullet and REORG-PLAN row. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>
|
Updated per maintainer answers: the promote guide is now centred on |
ingpaolodettori-dev
left a comment
ingpaolodettori-dev
left a comment
There was a problem hiding this comment.
Summary
Docs-only (README, REORG-PLAN, new docs/guides/promote-claude-workflow.md). I checked the claims against the code at 304bd03: every new link target exists, docs/index.md#maturity-labels resolves, the maturity table matches the legend and the get-started chooser, the Quick Start verify/teardown lines match deploy/compose/README.md (port 8080, /turn, Redis has no volume so down drops state), install-mocactl.sh requires Node 22+, and the promote guide's headless/TUI/exit-code/budget/bundle-fixed-at-creation statements match packages/mocactl/README.md, cli.ts and ADR-0038. The old #promoting-a-local-claude-code-workflow anchor still resolves (the README keeps that heading). No must-fix; comments below are non-blocking.
On the "Please check" items: running install.sh from a clone works (it never reads its own location and fetches docker-compose.yml from main), but the clone is unnecessary (comment 1). Dropping the Z-table is fine since the registry's Z section is authoritative.
Author: pdettori (MEMBER — maintainer)
Areas reviewed: Docs
Agent/IDE config (.claude/.vscode): none
Commits: 2 commits, all signed-off: yes
CI status: passing (14/14)
Body nit: the PR body still says the guide is moved "content verbatim" and asks whether the Redis-tunnel /promote flow is current, but 304bd03 rewrote the guide around mocactl promote. Please update the body so it matches what merges.
| > Anthropic-compatible model credential. | ||
|
|
||
| ```bash | ||
| git clone --recurse-submodules https://github.com/rossoctl/moca.git |
There was a problem hiding this comment.
suggestion: the clone (with --recurse-submodules, which also pulls pi-fork) is not needed: install.sh fetches docker-compose.yml from main (SH_COMPOSE_BASE_URL) and runs the published image, and never reads its own location. Mirror the Compose README's one-liner so the five-minute path really is one command:
curl -fsSL https://raw.githubusercontent.com/rossoctl/moca/main/deploy/compose/install.sh \
| ANTHROPIC_API_KEY=sk-ant-... sh| ([`deploy/claude/commands/promote.md`](../../deploy/claude/commands/promote.md)) that runs | ||
| `pnpm --dir <harness> promote` and writes straight to Redis over a tunnel you hold open. It needs | ||
| cluster access, so it does not fit a multi-user control plane, and this guide does not cover it. The | ||
| command and CLI remain in the repository; see ADR-0030 for how they work. |
There was a problem hiding this comment.
suggestion: ADR-0030 doesn't describe how the slash-command flow works (it only mentions "a thin Claude Code slash-command wrapper"). The detail this PR removes from the README (the --allowedTools launch flag, --home/--redis-url, --exclude-prompt, the two-tier credential scan, promoted.lock.json) now lives only in deploy/claude/commands/promote.md and the Knative-bannered docs/demos/promoted-workflow-demo.md. Point there instead of ADR-0030, which also covers the plan's "content loss from promote section" risk.
| | Terminology drift | OPEN | README:175 `SH_HARNESS_DIR`, :303 `@sh/experiments`; `serverless-harness`/`KAGENTI_`/`@sh/` still in 20 files outside specs/ADRs (`deploy/vm`, `P4-ON-P6.md`, demos) | | ||
| | Terminology drift | OPEN | README `@sh/experiments` (removed by PR 4; `SH_HARNESS_DIR` is a real variable read by `/promote`, not a leftover); `serverless-harness`/`KAGENTI_`/`@sh/` still in 20 files outside specs/ADRs (`deploy/vm`, `P4-ON-P6.md`, demos) | | ||
| | Glossary (2 terms) | OPEN | 39 lines | | ||
| | Maturity labels | OPEN | README badge still "MVP (Phase 1)" | |
There was a problem hiding this comment.
nit: this PR replaces the "MVP (Phase 1)" badge and adds the maturity table, so this row should read "FIXED by PR 4 (#492)" like the PR 1 rows.
| | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | ||
| | 1 (#488) | **Docs hygiene, no moves.** Fix the 2 broken `deploy/knative/README-authbridge.md` links and turn the 20 out-of-repo `docs/research/` references into plain text with a note; register the 11 unregistered specs; P6/P6.1 "implemented" and ADR-0034/0037 Accepted; banners on `executive-overview`, `experiment-results`, `packages/k8s-sandbox/{README,SMOKE}.md`; fix the demos README wording and the `deploy/vm/README.md` opening line. **Not done, carried forward:** ADR-0035/0040 status (left Proposed on purpose), banner for `deploy/knative/sandbox-inventory/README.md` (unconfirmed whether Knative-specific), `SECURITY.md:12` and the ADR-template placeholder (false positives), README stale items (PR 4) | link check shows only the 3 known false positives; every spec in `docs/specs/*.md` appears in the registry; ADR edits limited to Status lines | Editing ADR status lines vs the ADR-0041 Revisions precedent | | ||
| | 2 | **Migration guide completion** (`docs/migrating-from-knative.md`): env/config mapping, `mocactl` guidance, cron row + interim guidance for A/C, rollback, per-environment steps, status log; add the **removal-PR checklist** (6.6) as a draft file under `docs/notes/` or in the PR description | Each Knative banner target answers: what do I change, what breaks, how do I roll back; no removal date invented | Guidance for A/C may not exist (Q5): then state "no interim path, stay on Knative until round two" explicitly | | ||
| | 3 (this PR) | **Docs skeleton + tooling, no site yet.** `docs/index.md` (map, maturity legend), `docs/get-started/index.md` (CLI install + backend chooser with labels and a not-supported list), `docs/CONTRIBUTING-DOCS.md` (style guide, standard banners), offline link and anchor checker `scripts/check-doc-links.py` (`make check-links`, CI job `docs`), PR template. **Deferred:** `mkdocs.yml` (open question 12, and many docs link outside `docs/`, e.g. `../deploy/...`, which MkDocs would flag), lychee for external links, markdownlint, new CODEOWNERS entries (the `*` rule already covers `docs/`; docs owner is open question 10), section index pages for sections that have no content yet | `make check-links` passes on the whole tree; every link in the new pages resolves; chooser claims trace to the deploy READMEs | Chooser summarizes prerequisites that the deploy READMEs own; keep them in sync | |
There was a problem hiding this comment.
nit: two rows now say "(this PR)". PR 3 merged as #491, so this one should be 3 (#491).
| | Leave the Knative/KEDA deployment | [Migration guide](docs/migrating-from-knative.md) | | ||
| | Promote a Claude Code workflow | [Guide](docs/guides/promote-claude-workflow.md) | | ||
| | Look up a term | [Glossary](docs/glossary.md) | | ||
| | Call the HTTP API | [`docs/api/openapi.yaml`](docs/api/openapi.yaml), [Context service](docs/context-service.md) | |
There was a problem hiding this comment.
nit: docs/index.md lists api/harness-openapi.yaml here too. It's the data-plane API, including the /turn the Quick Start just called, so add it.
- Quick Start: use the one-line Compose install, no clone needed. - Promote guide: point to deploy/claude/commands/promote.md and the Knative promoted-workflow demo for the old flow, not ADR-0030. - README: list harness-openapi.yaml. - REORG-PLAN: mark the chooser, roadmap, docs index and maturity rows fixed; replace '(this PR)' with PR numbers. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>
|
Addressed in 1928bdb: one-line Compose install (no clone), promote guide points at |
Summary
README delta from the plan (
docs/REORG-PLAN.md, 5.4). Based onmainafter #491.previewinstead ofMVP (Phase 1).curl /turnfrom the Compose README) and teardown, themocactlinstaller line, and a link to the get-started chooser.docs/guides/promote-claude-workflow.mdis rewritten aroundmocactl promote(headless and the TUI/promote DIR): exit codes, session-fixed bundles, the byte budget, orchestrator dispatch. The older Redis-tunnel slash-command flow is one paragraph pointing atdeploy/claude/commands/promote.md. The README keeps a short summary and the Features bullet matches.@sh/experimentsreference and the cold-start wording; Documentation is a table linkingdocs/index.mdand both OpenAPI files; layout listsconfig-bundleandibac-stub.docs/REORG-PLAN.mdrecords what shipped and marks the rows this PR fixes.Not done
The plan's ~120-line target. The README is 297 lines (from 355) because Architecture, Features, How It Works and Dispatch Archetypes stay; the maintainer said not to trim them for now.
Notes
packages/mocactl/README.mdand ADR-0038 state (skills and commands). The old guide also describedCLAUDE.mdand memory travelling in the bundle; neither source saysmocactl promotecarries them.Verification
scripts/check-doc-links.pyreports 0 broken links; Prettier run on changed files; CI green on the earlier commits.Assisted-By: Claude (Anthropic AI) noreply@anthropic.com