docs: full rewrite -- persona-led ramps + 3-promise narrative#1252
Merged
Conversation
P0 fixes from docs audit panel (PR #1244 follow-up; full corpus rewrite plan): - env var: GITHUB_CLI_PAT -> GITHUB_APM_PAT in dependencies.md - schema: remove fictional scripts: object form (only dict[str,str] supported) - new section: apm cache {info,clean,prune} in cli-commands.md - deprecation banners on apm unpack across 6 pages (v0.14 removal) - baseline-checks count fixed to 8 across enterprise + integrations + reference - broken ../governance/ links retargeted to existing pages (4 files) - contributing lint commands now use --extra dev - Windsurf added to harness lists (index, what-is-apm, why-apm, key-concepts) - silent-success warning added to apm policy status (use --check for CI) - security callout on apm install --force (overwrite + drift bypass) Verified no-ops (CDO entries that did not require change): - apm marketplace plugin: zero command-form occurrences in docs - .codex/ deploy directory: VERIFIED real per integration/targets.py:466-484 Build: PASS, link validator clean, 53 pages built. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
New foundation chapter for the docs rewrite: - index.mdx (REPLACED): splash hero, 3-promise pitch, persona CardGrid - quickstart.mdx (NEW): 5-minute consumer ramp, 4 commands - concepts/what-is-apm.md (NEW): mental model, primitive orientation - concepts/the-three-promises.md (NEW): canonical 3-promise contract with src/ citations - concepts/primitives-and-targets.md (NEW): full compatibility matrix (single source of truth for primitive x harness reach) - concepts/package-anatomy.md (NEW): apm.yml + apm.lock.yaml schema - concepts/lifecycle.md (NEW): init/install/compile/run/audit verbs - concepts/glossary.md (NEW): 24 terms with sharp negations Verification: - CDO checkpoint: APPROVED, narrative arc cohesive - Editorial pass: 4 run-on splits in primitives-and-targets + lifecycle; no banned adjectives or patterns found - Build: 60 pages, all internal links valid Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
These files (AGENTIC-SYSTEM-DESIGN.md, CONTEXT-PACK.md) coordinate the multi-wave subagent execution. They live locally for the orchestrator and subagents but should not ship in the docs repo. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Slug pages (file.md → /file/) need ../target/ for sibling links because the trailing slash makes ./target/ resolve as a child path. Index pages still use ./target/ (the trailing slash is the parent directory). Affected: 6 slug pages across guides/, concepts/, introduction/. Fixes broken /apm/guides/pack-distribute/marketplace-authoring/ and similar 404s. enterprise/index.md is unchanged (already correct). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
10 new pages on the consumer ramp: install-packages, install-mcp-servers, deploy-a-bundle, run-scripts, update-and-refresh, manage-dependencies, authentication (slim), private-and-org-packages, drift-and-secure-by-default, governance-on-the-consumer-ramp. Each page drafted by a parallel doc-writer (draft -> verify-against-src -> editorial-self-pass), then chapter-level CDO checkpoint and editorial-owner voice sweep. CDO REVISE issues addressed: - manage-dependencies: corrected to document apm install <pkg> as a real manifest-mutating shortcut (verified in src/apm_cli/commands/install.py:114). - update-and-refresh: --runtime -> --target for chapter consistency. - update-and-refresh: dead audit-and-security link -> drift-and-secure-by-default. - concepts/primitives-and-targets: fallback corrected to 'minimal' (AGENTS.md only) per src/apm_cli/core/target_detection.py:206; previously claimed 'copilot' fallback which was drift. ASCII only. No sidebar blocks (Wave I owns sidebar). Build green; all internal links validate. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
10 new pages on the producer ramp: - author-primitives: skills, prompts, instructions-and-agents, hooks-and-commands, mcp-as-primitive - compile, preview-and-validate, pack-a-bundle, publish-to-a-marketplace, package-relative-links Each page drafted by parallel doc-writer (draft -> verify-against-src -> editorial), then chapter-level editorial-owner sweep + CDO checkpoint. CDO verdict PASS (no must-fix). Applied MED-severity polish: - hooks-and-commands: copilot hook filenames are <pkg>-<name>.json with bundled scripts under .github/hooks/scripts/<pkg>/, per src/apm_cli/integration/hook_integrator.py. - publish-to-a-marketplace: retargeted dead consumer link to legacy guides/marketplaces (Wave C does not yet cover marketplace install flow); retargeted enterprise/governance-overview to existing enterprise/governance-guide. - mcp-as-primitive: title-case fix on Primitives-and-targets link. - consumer/install-packages: corrected apm list description (lists scripts declared in apm.yml, not a tree view of installed packages), per src/apm_cli/commands/list_cmd.py:23. Surfaced by Wave D editorial. ASCII only. No sidebar blocks (Wave I owns sidebar). Build green; 80 pages, all internal links valid. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Wave E -- Enterprise ramp for the docs full rewrite. Lands 7 new pages
and modifies 2 legacy pages, completing the persona-led narrative for
platform owners and security leads.
NEW pages:
- governance-overview.md -- chapter map; 4 control surfaces, the
read-this-chapter-in-order list.
- apm-policy-getting-started.md -- minimal policy in 10 minutes;
schema spine.
- policy-pilot.md -- warn-first rollout pattern;
tighten-only inheritance via extends.
- enforce-in-ci.md -- apm audit --ci wiring; 8 baselines +
17 policy checks; --policy scopes.
- drift-detection.md -- the eight non-bypassable lockfile
baselines and what each one catches.
- security-and-supply-chain.md -- SecurityGate threat model; MCP
trust boundary; provenance.
- github-rulesets.md -- making apm audit --ci authoritative
via required-status-check rulesets.
MODIFIED pages:
- adoption-playbook.md -- retargeted to new chapter siblings.
- registry-proxy.md -- title cased; minor edits.
CDO REVISE applied (6 must-fix link retargets across 5 files):
- governance-overview.md src citation tightened
(install/phases/policy_gate.py delegates to install_preflight.py).
- adoption-playbook.md, github-rulesets.md, security-and-supply-chain.md,
policy-pilot.md: ../governance-guide/ -> ../governance-overview/;
../apm-policy/ -> ../apm-policy-getting-started/; legacy guides/
paths retargeted to new chapter pages. policy-reference kept as the
field-by-field schema reference.
Bridge fixes for sealed waves:
- consumer/governance-on-the-consumer-ramp.md: links to
enterprise/governance-overview at the chapter handoff.
- consumer/drift-and-secure-by-default.md: links to
enterprise/security-and-supply-chain and enterprise/drift-detection.
- producer/publish-to-a-marketplace.md: governance-guide retarget
-> governance-overview.
Build green: 87 pages, all internal links valid.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Adds one page per top-level apm command under reference/cli/, replacing the monolithic cli-commands.md surface (which will be retired in Wave I). Each page follows the same template (Synopsis, Description, Subcommands, Options, Examples, Behavior, Exit codes, Related) and was authored by a parallel doc-writer subagent verifying every flag against src/apm_cli/ commands/. Pages: init, install, uninstall, update, view, list, prune, outdated, cache, config, compile, run, preview, audit, targets, runtime, pack, unpack, policy, marketplace, search, mcp, deps, experimental. Wave F1 of the persona-led rewrite. Build green, 111 pages, all internal links valid. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- NEW: policy-schema, targets-matrix, baseline-checks, environment-variables - REWRITE: manifest-schema, lockfile-spec (drop W3C status block, modernize voice) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Wave G of the persona-led docs rewrite: troubleshooting/ (5 NEW + 1 REWRITE): - common-errors.md: catalog grouped by surface (install/compile/audit/run/auth) - install-failures.md: deep auth/network/lockfile/cache/recovery ladder - compile-zero-output-warning.md: diagnostic ladder for zero-output compile - ssl-issues.md (REWRITE): corporate proxy, GHES, GitLab self-managed, escape hatches - policy-debugging.md: which rule fired, inheritance, escape hatches - migration.md: from awd-cli, lockfile upgrades, target migration integrations/ide-tool-integration.md (REWRITE): - 703 line monolith collapsed to 137 line hub - detection rules, primitive flow, per-target reference pointers - delegates depth to targets-matrix, per-CLI reference, troubleshooting Build: 120 pages, all internal links valid. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Apply Wave H (oss-growth) and Wave I (Astro/Starlight expert) recommendations in one pass. Sidebar restructure - Replace legacy 'Understanding APM / Getting Started / Guides' tree with persona ramps: Start here, Use a package (Consumer), Author a package (Producer), Govern at scale (Enterprise), Integrations, CLI reference, Schemas and specs, Concepts, Troubleshooting, Contributing. - Autogenerate per-command CLI reference from reference/cli/. - Surface all 6 troubleshooting pages (was: only ssl-issues). Retired legacy - Delete reference/cli-commands.md (97KB monolith superseded by per-command pages; old URL redirects to /reference/cli/install/). - Delete getting-started/quick-start.md (duplicate of /quickstart/; old URL redirects). - Delete legacy guides/* (13 pages) and introduction/* (5 pages); content is now owned by consumer/, producer/, concepts/ ramps. New landing pages (4) - consumer/index.md - persona table + 4-command flow + recommended order. - producer/index.md - 5-step ladder Author->Compile->Validate->Pack->Publish. - producer/author-primitives/index.md - primitive type table + on-disk layout + recommended reading order. - troubleshooting/index.md - symptom triage table + escalation block. - reference/index.md - CLI by lifecycle phase + schemas table + conventions. Bulk link rewrite - Map ~25 legacy /apm/guides/* and /apm/introduction/* internal links to their new persona-ramp homes across the corpus (~30 files touched). Astro/Starlight polish - Add @astrojs/sitemap; emits /apm/sitemap-index.xml. - trailingSlash: 'always' (matches Starlight's link generation). - prefetch: prefetchAll on viewport. - editLink + lastUpdated enabled. - expressiveCode: github-dark + github-light themes, wrap defaultProps, borderRadius. - starlight-llms-txt: customSets per persona ramp + CLI reference; exclude contributing/. - head meta: theme-color, og:type, twitter:card. - Comprehensive redirects map (~25 entries) for any legacy URL referenced from external sources. Build: 98 pages, 127 HTML files, all internal links valid, sitemap generated. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Apply explicit github-dark/github-light theme pair so dark mode picks up high-contrast syntax colors instead of falling back to the default single theme. Add small structural styleOverrides: - borderRadius 0.5rem (matches Starlight card radius) - borderWidth 1px (subtle, single-pixel frame) - codeFontSize 0.875rem + lineHeight 1.5 (consistent body rhythm) - frames.shadowColor: transparent (drop the heavy default drop-shadow) Colors are intentionally left to each theme so terminal frames keep proper contrast in both light and dark modes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add an agentic system that per-PR detects doc-corpus drift,
classifies impact (no_change | in_place | structural), and orchestrates
a CDO + doc-writer + python-architect + editorial-owner + growth-hacker
panel that emits a single advisory comment.
Components:
- .apm/skills/docs-sync/ -- orchestrator (single-writer interlock,
7-step checklist, 15-call ceiling, ALIGNMENT LOOP bounded N<=3)
- .apm/skills/docs-impact-{classifier,localizer,architect}/ -- 3-layer
retrieval funnel siblings (L0 path gate / L1 grep / L2 LLM)
- .apm/agents/{editorial-owner,cdo}.agent.md -- new personas
- .apm/docs-index.yml -- corpus manifest (TOC + abstracts + symbol map)
- .apm/skills/docs-sync/evals/ -- trigger evals (20) + 3 content evals
- .github/workflows/docs-sync.md -- gh-aw workflow, rung-1 label-gated
(pull_request_target + 'if:' label-name guard, fork-safe)
Rung 1 rollout: requires 'docs-sync' label. Companion PR (Step 7)
requires second label 'docs-sync-confirm' as A9 supervised execution
boundary.
Design followed the genesis skill; full case study with mermaid
diagrams + design-pattern justification archived in session files
(docs-sync-skill-design.md).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- gh aw compile docs-sync (0 errors, 0 warnings) - Add 'checkout: false' frontmatter as defense-in-depth against the pwn-request attack (we never need PR head -- 'gh pr diff' returns inert text). Combined with read-only permissions, arbitrary code in the PR head is physically unreachable from the workflow. Compiled lock file pins: - microsoft/apm-action@v1.7.2 (b48dd081) - github/gh-aw-actions/setup@v0.71.5 - all transitive actions to SHAs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Shadow-evaluated against 8 recently-merged PRs (1244, 1240, 1259, 1239,
1238, 1257, 1261, 1263). Findings persisted to session files; this
commit applies the 4 high-priority gaps surfaced by the eval.
1. Add 'in_place_resolved' verdict (classifier schema + SKILL.md).
PRs where the author already patched every affected doc page (1239,
1259) should silently succeed without an advisory comment. Killed
false-positive class.
2. Pass 'pr_doc_diff_paths[]' into the L2 classifier envelope, with an
explicit downgrade rule: if every scope_page is in
pr_doc_diff_paths, return in_place_resolved.
3. Add rename / breaking-change heuristic to the classifier. PR 1244
('apm update' verb swap) would have been miscategorized as in_place
without this -- the affected pages existed, but the shape of the
work is structural (page split + TOC delta).
4. Add section-grouping mitigation for >8-page cascades in the
orchestrator's Step 3. PR 1244's 9-page rename cascade would have
approached the 15-call ceiling at one writer call per page. Now
collapses to 2-3 section writer tasks when the same conceptual fix
repeats across pages in the same TOC section.
5. Also extend docs-index.yml: add pyproject.toml + uv.lock to
no_impact_paths (caught by PR 1263 eval); add also_consider_paths
for packages/apm-guide/.apm/skills/apm-usage/** + README + MANIFESTO
(caught by PR 1244 eval -- those touch downstream doc surfaces but
are not part of the human-facing corpus).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…f-update) Skill: .apm/skills/docs-sync executed as orchestrator (this thread) following Step 2 (architect) + Step 3 (fan-out writers) per the cascade-size mitigation introduced in commit 03aa3f4. Panel: 1 architect (doc-analyser) + 4 section writers (doc-writer) dispatched as parallel background subagents. 9 stale corpus pages collapsed to 5 LLM calls (well under the 15-call ceiling). Changes: - NEW: reference/cli/self-update.md (binary updater; auto-picked by Starlight autogenerate via sidebar.order: 5) - REWRITE: reference/cli/update.md (now describes the dep updater with consent gate; documents the back-compat shim) - REWRITE: consumer/update-and-refresh.mdx (verbs flipped; new --frozen, apm update, and apm self-update sections) - PATCH: reference/cli/install.md (add --frozen flag row, no-op nudge bullet, frozen-mode bullet, --frozen exit codes, fix --force note, retarget Related links) - PATCH: consumer/install-packages.md, manage-dependencies.md (Coming-from-npm Asides + flag references) - PATCH: concepts/glossary.md (new self-update + update entries; remove false 'NOT npm-equivalent' caveat from install entry) - PATCH: concepts/package-anatomy.md, quickstart.mdx (Coming-from- npm framings updated) Follow-up: 13 secondary mentions of 'apm install --update' (flag form, still valid) remain in drift-and-secure-by-default, troubleshooting, registry-proxy, security-and-supply-chain, authentication, outdated, and publish-to-a-marketplace. Flag is retained per PR #1244; prose can shift to 'apm update' command form in a follow-up sweep. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Landing page (index.mdx): - Restore manifest example as conversion artifact (12 lines, multi-host proof: GitHub + GitLab + Azure DevOps + Bitbucket + MCP servers) - Promote three promises back from italic prose into 3-card grid (Portable / Secure / Governed; drop weak 'Any git host' card -- proof moves into the manifest example) - Keep new npm-analogy hero tagline - Keep install command above the fold (one bash block, Windows footnote) - Add new 'Manage MCP servers by manifest' section after the manifest example (positions APM's MCP-as-dependency model as the novel differentiator vs. ad-hoc per-IDE MCP config) - Deduplicate persona router (was rendered twice as LinkCards + Cards; now appears exactly once as 'Pick your path') - Replace verbose 'Open Source & Community' paragraph with one-line footer Authentication page (consumer/authentication.md): - Reframe opener: any git host you can 'git clone' from, not GitHub-and-ADO-only - Expand '30-second answer' with GitLab and generic-git rows - Add 'GitLab (SaaS or self-managed)' section: GITLAB_APM_PAT -> GITLAB_TOKEN -> git credential helper precedence - Add 'Bitbucket, Gitea, and any other git host' section: credential helpers only, by design (if 'git clone' works, 'apm install' works) - Update frontmatter description to reflect multi-host coverage - Update 'Going further' link to existing enterprise/security page astro.config.mjs: - Remove stale '/getting-started/first-package' -> '/producer' redirect (target lacked /apm/ base; conflicted with sidebar entry for the same slug -- the page exists and is in the sidebar) All claims grounded against src/apm_cli/core/token_manager.py (GitLab and generic-host auth), docs/src/content/docs/reference/ manifest-schema.md (MCP registry-prefixed form, ADO _git segment required), and existing source repo for handle currency. Driven by the docs-sync skill: doc-analyser architect plan + 2 parallel doc-writer subagents + orchestrator-applies + S7 verify. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Split install into per-OS Tabs (macOS/Linux | Windows) with syncKey='os' so the choice persists across the site. - Separate APM bootstrap (curl|sh / irm|iex) from sample-package install -- they are two distinct steps, not one block. - Drop standalone 'Manage MCP servers by manifest' H2 -- the manifest example already shows MCP entries (io.github.*) as first-class deps; a separate section was redundant. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Conflicts resolved: - docs/src/content/docs/guides/dependencies.md: kept HEAD deletion (the rewrite replaces guides/ with the consumer/producer/enterprise ramp structure; dependency content is now split across consumer/manage-dependencies.md and reference/manifest-schema.md). - docs/src/content/docs/reference/lockfile-spec.md: kept HEAD's simplified Lifecycle table at lines 190-200, which already covers apm install / --frozen / apm compile / apm audit / apm prune / apm view --lock / apm unpack. The new 'apm update' interactive command and richer --frozen exit semantics added on main are documented in dedicated CLI reference pages (reference/cli/update.md, reference/cli/install.md) and consumer guides (consumer/update-and-refresh.mdx, consumer/install-packages.md consumer/manage-dependencies.md), so the lockfile spec stays focused on the file format itself. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Three links in the rewrite still pointed at the old 'getting-started/authentication' page with an '#authenticating-with-microsoft-entra-id-aad-bearer-tokens' anchor that no longer exists on the new consumer page (the in-depth AAD bearer content moved to enterprise/security.md). The legacy /getting-started/authentication path itself redirects to /consumer/authentication via astro.config.mjs, but the redirect drops the anchor and the new page intentionally stays brief. Repointed links: - enterprise/security.md:302 -- self-link inside the same page, now '(#azure-devops-aad-bearer-tokens)'. - integrations/ci-cd.md:36 -- '../../consumer/authentication/' (top-level guide for tokens and priority rules). - integrations/ci-cd.md:136 -- '../../enterprise/security/#azure-devops-aad-bearer-tokens' (deep link to the anchor that actually exists). Verified: curl-and-grep on the rendered enterprise/security/ page shows id='azure-devops-aad-bearer-tokens' is present. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…consistency tests; correct stale apm install --policy doc snippet - apm install: regenerate .agents/ skills + .github/agents/ from current .apm/ sources (resolves APM Self-Check drift). - tests/unit/policy/test_help_consistency.py: retarget DOCS_PATH to the per-command files reference/cli/audit.md and reference/cli/policy.md (legacy reference/cli-commands.md was retired in 39d5740). Switch bullet helper to a markdown-table-row helper to match the new docs. - enterprise/apm-policy-getting-started.md: replace 3 invalid 'apm install --policy ...' examples with the correct surfaces: 'apm policy status --policy-source ...' for preview and 'apm audit --ci --policy ...' for CI gating. apm install has no --policy flag. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Local re-install with apm v0.12.2 produced relative path '../instructions/tests.instructions.md' for the test-coverage-expert agent's reference to .apm/instructions/tests.instructions.md, but microsoft/apm-action@v1 (CI) ships v0.13.0 which produces '../../.apm/instructions/tests.instructions.md'. Re-running install under v0.13.0 locally restores parity and clears APM Self-Check. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The merge from main brought in @astrojs/sitemap as a direct dependency (added in 39d5740 wave-i for sitemap generation) while preserving the @astrojs/sitemap entry in 'overrides' from main. npm 11 rejects the overlap with EUSAGE 'Override conflicts with direct dependency', which the cli surfaces as the misleading 'no package-lock.json' message. Drop the override (the direct dep already pins the same version) and regenerate the lockfile. Verified: npm ci + npm run build succeed locally; 100 pages built; all internal links valid. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
apm run is an optional npx-style script runner, not required to use any installed package. Surfacing it as step 4 of the quickstart pushed every new user into runtime-CLI installation and prompt orchestration before they had even read what their installed package does. - Drop the dedicated 'Run an agent' step from quickstart; replace with a short 'What next' note pointing at consumer/run-scripts/ for users who want it. - Update the scripts: bullet earlier in the page to flag the experimental status instead of teasing step 4. - Add a caution admonition to consumer/run-scripts/ marking the runner as experimental and explicitly off the critical path. Verified: 100 pages built; all internal links valid. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…t all primitives apm compile only consumes instructions/*.instructions.md (and optionally one chatmode to prepend); it produces AGENTS.md / CLAUDE.md / GEMINI.md root context files plus per-harness rules trees (.github/instructions/, .claude/rules/, .cursor/rules/*.mdc, .windsurf/rules/). Other primitive types (prompts, skills, agents, chatmodes-as-content, hooks, commands, MCP) are deployed by apm install directly into the harness directories that consume them; compile does not touch them. Verified against src/apm_cli/compilation/ -- AgentsCompiler and DistributedAgentsCompiler iterate primitives.instructions and primitives.chatmodes only, never primitives.prompts / skills / agents. - producer/compile.md: rewrite to scope the description, table, and pitfalls to instructions only; clarify install vs compile boundary. - reference/cli/compile.md: rewrite Description to name instructions as the only input and call out the install handover for everything else. Verified: 100 pages built; all internal links valid. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…t cards Per maintainer feedback, surface the experimental apm run pointer right after the success summary, before the three persona cards, so users considering 'how do I actually run things' see the answer before they scroll into producer / governance ramps. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…or other targets GitHub Copilot natively reads .github/instructions/*.instructions.md (with their applyTo: frontmatter) that apm install already deploys, so the AGENTS.md / copilot-instructions.md output of compile is nice-to-have rather than required for that target. Other targets (claude, cursor, codex, gemini, opencode, windsurf) load instructions through a root context file or harness-specific rules folder that compile generates -- without it, the harness will not pick the instructions up. Add an explicit 'Compile required?' column to the per-target table and a callout in both the producer guide and the CLI reference. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.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
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.
What this PR does
Full rewrite of the APM docs corpus, structured as persona-led ramps anchored on the 3-promise narrative from the README (Compose Fearlessly / Distribute Trustlessly / Run Anywhere). Replaces the current TOC's mix of conceptual + reference + persona pages with a clear progressive-disclosure surface for new readers landing cold.
This is a multi-wave delivery; the PR will grow as waves land.
Approach
Designed via the
genesisskill (8-step process). Persisted plan + handoff packet in.docs-rewrite-plan/(committed in Wave A).Each wave runs:
npm run build+ Starlight link validator must pass)A final astro-starlight-expert pass will land before un-drafting.
Locked decisions (all 5 confirmed by user)
index.mdx,what-is-apm.md, andthe-three-promises.mdWave status
2215a4f3)beacf07e)Wave B contents (this commit)
index.mdx(REPLACED): splash hero + 3 promises (hook + 30s proof + 10s demo each) + persona CardGridquickstart.mdx(NEW): 5-minute consumer ramp, 4 commands, npm calloutconcepts/what-is-apm.md(NEW): mental model + primitive orientation tableconcepts/the-three-promises.md(NEW): canonical 3-promise contract with src/ citations per promiseconcepts/primitives-and-targets.md(NEW): full compatibility matrix (canonical SSOT for primitive x harness reach)concepts/package-anatomy.md(NEW):apm.yml+apm.lock.yamlschema referenceconcepts/lifecycle.md(NEW): init -> install -> compile -> run -> audit verb sequenceconcepts/glossary.md(NEW): 24 disambiguating terms with sharp negationsWave B verification
Open items captured during Wave B
apm initwritestargets:(plural) but the manifest model readstarget:(singular). Worth a separate fix; docs use the schema field for now.apm run <prompt-name>auto-discovery after install reports "No scripts found" in some cases — quickstart sidesteps with explicitscripts:path. Worth a separate ticket.--trust-transitive-mcpopt-in + policy allow-listing today; an interactive prompt is on the Promise 2 roadmap. Glossary marks accordingly.Cost / scope
How to review
/apm/concepts/the-three-promisesfirst (it locks the contract)/apm(landing) and/apm/quickstartto feel the consumer ramp.docs-rewrite-plan/AGENTIC-SYSTEM-DESIGN.mdif curious about provenance