docs(zcp): add Zerops Control Plane docs section#337
Open
fxck wants to merge 23 commits into
Open
Conversation
Reconciles the pv-zcp positioning manifesto and kh-zcp ops manual into a single ZCP docs set. Adds: - /features/coding-agents.mdx — features-page positioning anchor with ZCP MCP vs hosted-service framing, comparison vs Lovable/E2B/Replit/ Codespaces/Cloudflare, capability-by-job table. - /features/local-remote-development.mdx — paired three-modes story (Local+VPN / Cloud IDE on ZCP / Native IDE over SSH). - /zcp/ — 17-page reference subsection: overview, quickstart, glossary, how-it-works, choose-workspace + hosted/local setup, trust-model + tokens + production-policy + auditing, create-or-adopt + build-and- verify + delivery-handoff + package-running, agent-workflow contract reference, troubleshooting. - Mermaid diagrams: where-ZCP-runs architecture, bootstrap-routes decision tree, develop-flow loop, trust-model blast radii. - CustomCard pairs and DocCardList for entry-point pages. Sidebar: new "Zerops Control Plane" subsection under References, between Command Line Tools and Networking. "Infrastructure for Coding Agents" added at the bottom of the Features section. Removes the orphan /guides/local-development.mdx (superseded by /zcp/setup/local-agent-bridge and /features/local-remote-development). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Term discipline pass — Codex-verified across all ZCP pages: - Operational verbs (validates, reads, refuses, exposes, authorizes, picks up, records, enforces) now subject "the MCP" / "ZCP MCP", not bare "ZCP". - Container/wrapper references (token storage, env vars, isolation flags, SSHFS mounts, the thing you add to a project, what you SSH into) now subject "the hosted workspace" or "the `zcp` service". - "ZCP" reserved for the umbrella concept (titles, sidebar label, comparison-section product reference, the kept aphorism). Specific corrections: - VPN reach in local mode — your laptop reaches managed services via VPN; the MCP itself talks to the Zerops API directly. - Agent-workflow Workspace layer — in hosted mode the wrapping service also runs the bundled agent CLI; in local mode the agent runs in your editor and talks to the MCP. - Trust-model isolation flags — `envIsolation: none` / `sshIsolation: vpn service@zcp` are scoped to the `zcp@1` service, not "ZCP itself". - "Where ZCP runs" architecture — hosted on the project network vs local binary talking to the API with VPN as a separate concern. Linking: - features/coding-agents — CustomCard pairs in "Two ways to run it" now link to setup pages directly. MCP-and-permissions cards link to the named tool sections in agent-workflow. Trust model linked inline. Glossary added to the bottom DocCardList. Quickstart promoted from bottom-only to a body mention. - features/local-remote-development — Browser Cloud IDE section links to Provision a hosted workspace; Picking a mode footer links to Choose your workspace; Next steps expanded with hosted-workspace, choose-workspace, glossary. Other: - Public-preview/dev-staging conflation removed across pages — the dev/staging rule is a security principle, independent of preview status. - Recipe-UI gotchas (deploy-button label) cut from quickstart and hosted-workspace — that's Zerops recipe UX, not a ZCP gotcha. - Glossary moved to end of ZCP sidebar. - Sidebar label: "Zerops Control Plane" → "Zerops Control Plane MCP". - Table-balancing CSS extended to /features/coding-agents and /features/local-remote-development. - `zerops.yml` → `zerops.yaml` (canonical). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Rewrite /features/coding-agents.mdx as the canonical intro for Zerops's Infrastructure for Coding Agents: explicit feature claims, a Bootstrap → Develop → human-reviewed PR-to-prod story, and a landscape section positioning ZCP against PaaS/VPS MCPs, CDEs, bundled agent platforms, local agents, sandboxes, and SDKs. New components: - IntroAgentVisual — ASCII grid with overlaid agent + recipe logos - CodingAgentsTopology — remote/local topology toggle - AsciiGraph — shared ASCII renderer with hl/accent variants - Note "tip" variant Plumbing: - markdown-source plugin so the ASCII visuals also render in the .md output served to LLMs (grid.cjs shared between React and converter) - Recipe and landscape image assets Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Apply the four-sweep editorial pass described in zcp-audit.md across apps/docs/content/zcp/ and the /features/coding-agents intro. Sweep 1 — structural deletions - Remove three orphan stubs (workflows/build-and-verify-app, create-or-adopt-services, delivery-handoff) and their stale entries in static/llms.txt; no internal links pointed at them. - Fix the factual narrowing on /features/coding-agents: production handoff is no longer presented as "PR-only" — the prose now matches the five release paths /zcp/workflows/promote-to-production lists. Sweep 2 — hierarchy - overview.mdx opens with the public-preview caveat and a four-bullet section map; the duplicated "Start here" tables are gone. - quickstart.mdx "Next steps" trimmed to dedupe with overview. - concept/how-it-works.mdx kept as the work-loop concept; the failure and delivery tables now link to their canonical homes. - reference/agent-workflow.mdx sharpened as the label catalog: the develop mermaid (now lives in concept) and the duplicate runtime- layouts and failure-categories tables are gone, replaced with links. Apologetic Bootstrap framing at line 15 deleted; the label is kept. - reference/index.mdx grown from a 13-line stub to a real Reference landing with use-case routing and common combinations. Sweep 3 — consolidation - security/trust-model.mdx drops the duplicate confirmation-gates table and ZCP_API_KEY injection prose; both now link to tokens-and-project-access#what-zcp-enforces-for-destructive-actions. - glossary.mdx gains explicit anchor IDs (#runtime-layout, #failure-category) so the upstream links resolve. Sweep 4 — vocabulary - "Production promotion" (noun) → "Production release" everywhere; build-with-zcp anchor renamed to #prepare-production-release. - Drop "operating loop" → "work loop", "workflow-guided" → "generated workflow", "bounded operations" → "project-scoped operations", "opinionated"/"done gate"/"done criteria" → concrete phrasing. "Multi-environment promotion" on the features page reworded to "real dev/stage/prod release flow". Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The AsciiGraph and IntroAgentVisual components rely on every glyph (letters, digits, spaces, box-drawing characters │ ─ ▼ └ ┘) being exactly 1ch wide. With the previous --ifm-font-family-monospace stack, browsers were falling back to a different font for box-drawing characters on macOS, Windows, and especially Android — drifting the diagrams off-grid. - Add self-hosted JetBrains Mono Regular woff2 under static/fonts/. - Preload the font in headTags so the first paint is already on-grid (no FOUT/CLS visible to the reader). - Introduce --ascii-graph-font with JetBrains Mono as the lead, system monospace as fallback; apply it to .ascii-graph and .intro-ascii. - Disable contextual alternates and ligatures on those elements so adjacent glyphs cannot collapse or shift. Code blocks elsewhere on the site keep the default monospace stack; this change is scoped to the ASCII diagrams that need a strict grid. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The top-right corner of the loop-back arrow sat at column 50; every │ below it and the ┘ at the bottom sat at column 51. Added one more ─ between ◀ and ┐ so the corner aligns with the vertical line. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reconciles the pv-zcp positioning manifesto and kh-zcp ops manual into a single ZCP docs set. Adds:
Sidebar: new "Zerops Control Plane" subsection under References, between Command Line Tools and Networking. "Infrastructure for Coding Agents" added at the bottom of the Features section.
Removes the orphan /guides/local-development.mdx (superseded by /zcp/setup/local-agent-bridge and /features/local-remote-development).
What Type of Change is this?
Description (required)
Related issues & labels (optional)