docs(landing): align with three-pillar spine#855
Merged
danielmeppiel merged 1 commit intomainfrom Apr 22, 2026
Merged
Conversation
…erned) The landing page was still describing APM purely as a portability story. After PR #851 elevated governance and security to first-class pillars in the README, the docs landing didn't match. - Rewrite intro to the same Portable/Secure/Governed framing as README - Replace 'Dependencies That Resolve' card with 'Governed by policy' (transitive resolution is now mentioned inside the portability card) - Rename 'Supply Chain Security' -> 'Secure by default' and tighten copy to match what install scanners actually cover (hidden Unicode, not PI) - Link governance card to the new flagship Governance Guide - Mention apm.lock.yaml explicitly inside the portability card No structural changes -- still 4 cards, same hero, same Quick Start, same example block. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the Starlight docs landing page copy (docs/src/content/docs/index.mdx) to match the post-#851 "three-pillar" framing (Portable by manifest / Secure by default / Governed by policy), replacing the previous portability-only positioning.
Changes:
- Rewrites the intro paragraph to mirror the new three-pillar narrative.
- Re-themes the landing cards to the three pillars (plus "Any git host"), including lockfile and governance guide references.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/index.mdx | Refreshes the landing page messaging and card set to align with the three-pillar spine and link to governance docs. |
Copilot's findings
Comments suppressed due to low confidence (2)
docs/src/content/docs/index.mdx:33
- Non-ASCII punctuation (em dashes) appears in this card copy. The repo requires documentation content to be printable ASCII only; please replace em dashes with ASCII equivalents (e.g., "--").
One `apm.yml` declares skills, instructions, prompts, agents, hooks, plugins, and MCP servers. Transitive dependencies resolve like npm or pip; `apm.lock.yaml` pins exact versions for reproducible installs across Copilot, Claude Code, Cursor, OpenCode, and Codex.
</Card>
<Card title="Secure by default" icon="approve-check-circle">
Skills, prompts, instructions, hooks — everything agents execute is an attack surface. `apm install` scans packages for hidden Unicode and other tampering before they reach your agents; `apm audit` reports the full chain of trust.
</Card>
docs/src/content/docs/index.mdx:36
- Non-ASCII punctuation (em dash) is used in this card description. Documentation in this repo must be printable ASCII only; please replace the em dash with an ASCII alternative (e.g., "--").
<Card title="Governed by policy" icon="setting">
`apm-policy.yml` lets platform teams allow-list dependencies, restrict deploy targets, and enforce trust rules at install time — across every repo, from a single source of truth. See the [Governance Guide](/apm/enterprise/governance-guide/).
</Card>
- Files reviewed: 1/1 changed files
- Comments generated: 2
Comment on lines
21
to
+25
| **An open-source dependency manager for AI agents.** Think `package.json`, `requirements.txt`, or `Cargo.toml` — but for AI agent configuration. | ||
|
|
||
| AI coding agents need context and capabilities to be useful — instructions, skills, prompts, plugins, MCP servers. But today, every developer configures theirs differently. Copying files, writing instructions from scratch, sharing knowledge in Slack threads. None of it is portable. None of it is versioned. | ||
| AI coding agents need context and capabilities to be useful — instructions, skills, prompts, plugins, MCP servers. But today every developer configures theirs differently. Nothing is portable. Nothing is reproducible. Nothing is governed. | ||
|
|
||
| APM fixes this. You declare your project's agent configuration once in `apm.yml` — skills, prompts, instructions, agents, hooks, plugins, MCP servers — and every developer who clones your repo gets a fully configured agent setup in seconds. New developer joins the team? `git clone`, `cd`, `apm install`. Done. | ||
| APM fixes this. You declare your project's agent configuration once in `apm.yml` — and every developer who clones your repo gets a fully configured agent setup in seconds, locked to exact versions, scanned for hidden threats, and gated by the policies your organization defines. |
There was a problem hiding this comment.
Non-ASCII punctuation (em dashes) is used in these lines. Per the repo's encoding rules, docs must stay within printable ASCII to avoid cross-platform encoding issues; please replace these with ASCII alternatives (e.g., "--" or "-" and adjust spacing as needed).
This issue also appears in the following locations of the same file:
- line 29
- line 34
| <Card title="Any Git Host" icon="github"> | ||
| Install from GitHub, GitLab, Bitbucket, Azure DevOps, GitHub Enterprise, or any self-hosted git server. | ||
| <Card title="Governed by policy" icon="setting"> | ||
| `apm-policy.yml` lets platform teams allow-list dependencies, restrict deploy targets, and enforce trust rules at install time — across every repo, from a single source of truth. See the [Governance Guide](/apm/enterprise/governance-guide/). |
There was a problem hiding this comment.
This copy says policy can "restrict deploy targets", but the policy engine's target restrictions are expressed as compilation targets (the target field in apm.yml, enforced by the compilation-target check). Consider rewording to "restrict compilation targets" (or similar) to match the actual schema and checks.
Suggested change
| `apm-policy.yml` lets platform teams allow-list dependencies, restrict deploy targets, and enforce trust rules at install time — across every repo, from a single source of truth. See the [Governance Guide](/apm/enterprise/governance-guide/). | |
| `apm-policy.yml` lets platform teams allow-list dependencies, restrict compilation targets, and enforce trust rules at install time -- across every repo, from a single source of truth. See the [Governance Guide](/apm/enterprise/governance-guide/). |
This was referenced Apr 22, 2026
danielmeppiel
added a commit
that referenced
this pull request
Apr 23, 2026
* chore: prepare v0.9.2 release Bumps version to 0.9.2 and finalizes CHANGELOG with one-line summaries for each PR merged since 0.9.1. Highlights: - ADO AAD bearer-token auth (#856) - Governance Guide + enterprise docs IA refactor (#851, #858) - Merge Gate orchestrator + single-authority aggregation (#865, #867) - Landing + first-package docs rewrite (#855, #866) - gh-aw imports migration (#864) - Custom-port surfacing fix (#804) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci: simplify merge-gate to single pull_request trigger The dual-trigger pattern (pull_request + pull_request_target with concurrency cancel-in-progress) shipped in #865 was over-engineered. It produced TWO 'gate' check-runs per SHA -- one SUCCESS, one CANCELLED -- and branch protection's status-check rollup treats CANCELLED as failure, so PRs were silently BLOCKED unless an admin overrode (which masked the bug on #867). GitHub Actions has no primitive for 'either of these events succeeded'. World-class OSS projects (kubernetes, rust, deno, next.js) accept this and use a single trigger. The cost: a dropped 'pull_request' webhook (rare; observed once on PR #856) requires manual recovery. Recovery paths now documented at top of file: - push empty commit - gh workflow run merge-gate.yml -f pr_number=NNN - close + reopen PR Replaces the dual-trigger + bootstrap-fetch dance with a clean two-job flow: resolve-sha (handles workflow_dispatch input or PR head) then gate (sparse checkout + run script). Same script, same exit codes, same EXPECTED_CHECKS env. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci: collapse merge-gate into a single job (one check-run in PR UI) The two-job split (resolve-sha + gate) created two visible check-runs. Inlining the SHA resolution as a step within the gate job leaves only one check-run -- 'Merge Gate / gate' -- on the PR. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- 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.
After PR #851 restructured the README around Portable by manifest / Secure by default / Governed by policy, the docs landing page (
docs/src/content/docs/index.mdx) was still on the old single-pillar (portability-only) framing. This brings it back in line.What changed
apm.lock.yamlmention and folds in the transitive-resolution point.apm audit.Validation
npm run build-- 44 pages, all internal links valid, 8.12s.apm.ymlexample block.Why a separate PR
PR #851 already merged. Keeping this on its own branch makes the diff trivially reviewable and decouples landing copy from the (much larger) governance guide change.
cc @sergio-sisternes-epam