Flip the narrative to the P6 runtime (ADR-0041)

[pdettori]

Flip the narrative to the P6 runtime (ADR-0041)

PR3 of the ADR-0041 rollout. Docs and comments only — no behavior change.

Stacked on #485. Until #485 merges, this diff shows the whole branch; once it merges, GitHub
reduces this PR to the four narrative commits (docs: flip the README…, docs: flip CLAUDE.md…,
chore: label the Knative demo targets…, docs: banner the Knative demos…). Merge #485 first.

Flipped surfaces

• README.md — P6-first tagline and platform badge, intro (with the deprecation callout), Why table, architecture mermaid + component table + note, Features, a compose-first Quick Start (deploy/compose/install.sh, with pointers to deploy/vm and deploy/k8s), "Legacy: the Knative + KEDA deployment (deprecated)" replacing "Deploy on OpenShift" (TOC fixed), How It Works, annotated Dispatch Archetypes (A and C marked "deprecated path only", with the owed-P6-follow-ups note), a new repository tree, and Evidence/Documentation/Status updates.
• CLAUDE.md — P6 overview paragraph (supervisor, gRPC relay sandbox execution, deprecation note); tree comments updated for k8s-sandbox, knative-server (name historical — P6-load-bearing), deploy/knative (DEPRECATED) plus the added deploy/k8s line; Dockerfile comment fixed to node:24-alpine.
• Makefile — DEPRECATED comment blocks on the four demo targets that drive deploy/knative/ scripts (demo-remote-sandbox, demo-promoted-workflow, demo-multiuser, mocactl-quickstart), each pointing at a current-runtime walkthrough.
• Dockerfile — comment above the kubectl install (it serves only the deprecated path's KubectlTransport) and above the CMD entrypoint (the HTTP server is the Knative Service's container; the P6 supervisor forks src/worker.ts instead).
• .github/workflows/build.yaml — the moca-sandbox matrix entry labeled as the deprecated-path image (serves setup-ocp.sh only).
• docs/demos/ — deprecation banner under the title of the three Knative-path demos (moca-demo, remote-sandbox-demo, promoted-workflow-demo), each pointing at vm-multi-user-demo.md; index rows prefixed "(deprecated path)"; the SMOKE.md mention annotated. The vm-* walkthroughs are untouched.

Dead-end check (README)

grep -n "deploy/knative\|Knative\|KEDA" README.md → 13 hits, every one in an allowed place: the intro deprecation callout, the TOC, the Legacy section, the annotated Dispatch Archetypes, the labeled repository-tree entry, the annotated Evidence bullet, the Roadmap's historical reference, and the migration-guide link.

Verification

• make lint — exit 0 (shellcheck, prettier, hadolint — includes the Dockerfile comments)
• make typecheck — exit 0
• make test-deploy — exit 0

Assisted-By: Claude (Anthropic AI) noreply@anthropic.com

[ingpaolodettori-dev]

Summary

The narrative flip is consistent. I reviewed only the four commits on top of #485 (git diff 84ef6e1 c9ecb66); the #485 commits are identical and get their own review there. The README now leads with P6, and the Legacy section and TOC anchor (#legacy-the-knative--keda-deployment-deprecated) resolve. No other doc linked the removed "Deploy on OpenShift" anchor. Every path in the new repository tree exists. CLAUDE.md's node:24-alpine matches the Dockerfile's two FROM lines. The Makefile/Dockerfile/build.yaml changes are comments only, and every walkthrough they point at (vm-multi-user-demo.md, vm-two-user-acceptance.md, deploy/vm/README.md) exists. The root CLAUDE.md change is benign descriptive text (no commands or hooks). It sits outside .claude/, so the §3.5a gate doesn't apply.

One suggestion: the compose Quick Start omits the model credential install.sh needs. Plus one nit. The #485 findings (the Discussions links, which are disabled on this repo, and two ADR nits) also show in this diff until #485 merges. Fix them there.

Author: pdettori (MEMBER — maintainer)
Areas reviewed: Docs (README, CLAUDE.md, demos), Makefile, Dockerfile, CI (build.yaml, comment-only)
Agent/IDE config (.claude/.vscode): none (root CLAUDE.md touched; read in full, text only)
Commits: 12 commits (8 from #485 + 4 narrative), all signed-off: yes
CI status: passing (check, lint, proto, deploy-scripts, k8s-kind-e2e, microvm-gates, hadolint, CodeQL, Trivy, DCO)

[ingpaolodettori-dev]

suggestion — This Quick Start won't produce a working turn as written. install.sh takes the model credential only from the environment (ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN/OPENAI_API_KEY/SH_MODEL_*, see its header), and the prerequisite line says a credential is needed but never shows how to pass it. The clone is also unnecessary: install.sh fetches docker-compose.yml from main (SH_COMPOSE_BASE_URL) and runs the published images, so a checkout doesn't change what runs (that's the compose README's separate "From a checkout" path). Suggest mirroring deploy/compose/README.md "Try it":

curl -fsSL https://raw.githubusercontent.com/rossoctl/moca/main/deploy/compose/install.sh \
  | ANTHROPIC_API_KEY=sk-ant-... sh

(or ANTHROPIC_API_KEY=... ./deploy/compose/install.sh if you keep the clone). Then add one line pointing at the compose README for sending the first turn, since the section currently ends at bring-up.

[ingpaolodettori-dev]

nit — The P6 architecture shows Redis as "session state + work queue" (and the component table at line 81 lists "work queue (Streams)"). Per this same README's Dispatch Archetypes note, the Streams work queue only feeds async fan-out, which is deprecated-path-only until the owed P6 follow-up lands. Consider dropping "work queue" from the P6 diagram/table, or marking it as "(async fan-out, deprecated path)".