docs: consolidate docs/ into mkdocs site (PER-190)#150
Merged
Conversation
Part of PER-190 docs consolidation. Removes pure duplicates already covered by the mkdocs site and migrates two small conceptual pages. - delete docs/README.md (superseded by mkdocs nav) - delete docs/cli-reference.md (stub; site-docs/reference/cli.md canonical) - delete docs/artifact-type-matrix.md (covered by concepts/artifact-types.md) - migrate docs/no-project-overrides.md → concepts/design-decisions.md - migrate docs/understanding-agent-skills.md → concepts/what-is-a-skill.md - nav: add What Is a Skill + Design Decisions under Concepts Refs PER-190
Part of PER-190. Migrates the larger conceptual docs into the mkdocs site as new pages, extracting still-valid framing from the legacy agentic-warehouse-design.md without re-adding operational detail that how-it-works.md intentionally drops. - new concepts/philosophy.md — three-questions framing + two-tier model - migrate docs/specs-vs-artifacts.md → concepts/specs-vs-artifacts.md - migrate docs/spec-driven-development.md → guides/spec-driven-development.md - delete docs/agentic-warehouse-design.md (framing extracted into philosophy.md; bulk already covered in how-it-works.md and artifact-types.md) - nav: add Philosophy + Specs vs. Artifacts under Concepts; add Spec-Driven Development under Guides Refs PER-190
Part of PER-190. Moves the legacy boot-context-design notes and historical migration records into docs/archive/. These predate the current artifact model (contexts + skills + knowledge + agents) and are opencode-centric. Still-valid framing (two-tier information model, three-tier context concept) was already extracted into the new concepts/philosophy.md during Phase B. The archive directory is kept in-repo so external references in older commits and write-ups continue to resolve. A new docs/archive/README.md explicitly redirects readers to the live mkdocs site. - move docs/boot-context-design/ → docs/archive/boot-context-design/ - move docs/migrations/ → docs/archive/migrations/ - add docs/archive/README.md with status table + mkdocs pointers Refs PER-190
Part of PER-190. Moves the 12-file contributor guide into a Contributing section of the mkdocs site so it gets search and proper navigation, and rewrites the root CONTRIBUTING.md as a thin entry point covering only environment setup (the part GitHub renders natively for PR authors). - move docs/contributing/*.md → site-docs/contributing/*.md - new site-docs/contributing/index.md as section overview - strip `← Back to CONTRIBUTING.md` headers (don't make sense in mkdocs) - fix internal references: contribution-workflow, documentation - nav: add Contributing section under Reference + Troubleshooting - rewrite CONTRIBUTING.md as thin entry point linking to mkdocs site Refs PER-190
Part of PER-190. Updates every live reference to a docs/ path that
moved or was archived during the consolidation. Working documents
under openspec/changes/ are left untouched — they describe historical
fix-ups and reference paths that were correct at the time.
- README.md: replace 7 broken docs/ links with mkdocs-site equivalents;
restructure Documentation section into Concepts / Guides / Reference
- CHANGELOG.md: repoint migration guide link to docs/archive/migrations/
- guides/creating-skills.md: point at the new What Is a Skill mkdocs page
- guides/{getting-started,beacon-yaml-reference}.md: repoint migration links
- libs/beacon/src/beacon/{core/dependencies/{resolver,manifest,frontmatter},
domains/distribution/orchestrator}.py: MIGRATION_DOC_URL constants now
point at docs/archive/migrations/artifact-dependencies-frontmatter.md
- libs/beacon/tests/{unit,integration}: update test assertions to match
- openspec/specs/{agent-requires-manifest,artifact-dependency-resolution}/
spec.md: update spec text to reference the archive path
Verified: pytest unit suite (1047 passed) and `mkdocs build --strict` both
green.
Refs PER-190
Contributor
OpenCode ReviewModel: I’ll inspect the remainder of the attached diff and focus only on regressions introduced by these documentation/archive changes. FindingsNo findings. Open QuestionsNone. Notes
Token UsageInput tokens: |
…ges (PER-190) Iterative restructuring pass on top of phases A-D: - New top-level Design section: philosophy and skills (moved from concepts/) - design/skills.md: merged what-is-a-skill + bundled-skills framing, reframed as 'thin skills, fat tools' / intermediate state perspective - guides/adopting-artifacts.md: merged interactive-adoption + syncing into a single page presenting interactive vs declarative adoption paths - New Contributing Back parent guide with three sub-pages: creating-skills, creating-knowledge-and-contexts, creating-agents - guides/contribute-warehouse.md moved to reference/ (it is reference, not a flow guide) - Deleted: team-collaboration.md (covered by symlink/sync/adoption pages), spec-driven-development.md (out of scope; openspec mentioned where relevant) - contributing/ docs reshuffled: site-docs/contributing/* moved to docs/contributing/ (agent-facing); top-level user-facing site-docs/contributing.md added as the public entry point - Knowledge / context two-tier framing rewritten: context is a curated collection of knowledge; progressive disclosure is an optimisation, not the definition Note: mkdocs.yml is left at the post-audit state (commit 2). This commit alone will not build a coherent nav; the branch endpoint does.
…fs (PER-190) Critical-read audit of the post-restructure site, then trimming. Page deletions (5 pages, -625 lines): - concepts/specs-vs-artifacts.md: 205-line essay; kernel idea fits in one bullet elsewhere - concepts/design-decisions.md: one-decision stub with unkept promise of more - guides/connecting-projects.md: covered by Quickstart Scenario B - guides/advanced-patterns.md: duplicated cli.md and beacon-yaml.md - tutorials/first-contribution.md: 80% duplicated day-to-day-workflow; unique 'stray edit' beat folded into the discard section Bug fixes: - artifacts/contexts/knowledge/error-handling.md → artifacts/knowledge/... in day-to-day-workflow.md (wrong path; would error on copy-paste) - warehouse-lint/github-actions.md: removed broken Python-standards link pointing to how-it-works.md; removed internal AGENTS.md reference Internal-ticket leak scrub (no PER-XXX in public docs): - bundled-skills.md (PER-150, PER-151) - contributing-back.md (PER-159) - reference/contribute-warehouse.md (PER-179) CLI reference gaps: - abc sync --yes flag added (auto-accept agent-required skills) - abc warehouse contribute --paths flag added (per-file commits) Section-level cuts: - bundled-skills.md: 'Bundled Skills in the Warehouse Template' (~25 lines) and duplicated record-skill walkthrough (~40 lines, already in pending-and-adoption.md) - artifact-types.md: 'How the Matrix Shapes Command Behavior' table + 'Summary' filler — content lives in cli.md and adopting-artifacts.md - index.md: removed 'Compared to Similar Tools' table per direction; collapsed wiki-vs-beacon paragraph into the multiplayer admonition - installation.md: 'What Gets Installed' single-row filler - quickstart.md: 'Day-to-Day Workflow' mini-block; capped Next Steps to 3 - day-to-day-workflow.md: 'Quick Reference' command table (duplicates cli.md and prose above it) - creating-skills.md: 'Full Template' YAML (Minimal Template above is enough) - beacon-yaml.md: 'Related Commands' duplicate of cli.md Nav reorder (mkdocs.yml): - Guides moved before Design (Guides is the entry point; Design is rationale for advanced readers) - Removed dead nav entries: specs-vs-artifacts, design-decisions, connecting-projects, advanced-patterns, tutorials section, top-level contributing.md page README cleanup: removed dead specs-vs-artifacts and design-decisions links from the Concepts section. Net result: 27 → 22 pages, ~4534 → ~3668 lines (-19%). All 19 live pages return 200; all deleted pages return 404. Build green.
Contributor
OpenCode ReviewModel: I’ll review only the provided PR diff, plus the repository instructions/context needed to apply the review rules. Findings
Open QuestionsNone. NotesReview limited to the attached diff. Token UsageInput tokens: |
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
1 participant
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.
Summary
Consolidates the legacy
docs/directory into the published mkdocs site at https://shadowsong27.github.io/agentic-beacon/. Implements PER-190 in seven phased commits.Net result on
site-docs/: 27 pages → 22 pages, ~4,534 → ~3,668 lines (-19%) since the post-restructure baseline. Across the whole PR, ~5,800 lines of duplicate/stale markdown removed fromdocs/, the mkdocs site reorganised into a Concepts / Guides / Design / Reference structure, and the rootCONTRIBUTING.mdreduced to a thin entry point.Linear: PER-190
Commits
affafe78bccffaa9b1edf0de0d27a88226aaa6272c6d13c31Phase highlights
Phases A–D (commits 1–4)
docs/README.md,docs/cli-reference.md,docs/artifact-type-matrix.md); migratedocs/no-project-overrides.md→concepts/design-decisions.md(later trimmed); migratedocs/understanding-agent-skills.md→concepts/what-is-a-skill.md(later merged intodesign/skills.md).concepts/philosophy.md(later moved todesign/philosophy.md); migratedocs/specs-vs-artifacts.md(later trimmed); deletedocs/agentic-warehouse-design.md.docs/archive/rather than deep-extract from ~3,300 lines that predate the current artifact model.docs/contributing/*.mdfiles into the site (later moved back todocs/contributing/as agent-facing material); rewrite rootCONTRIBUTING.mdas a thin entry point.Phase E — cross-reference sweep (commit 5)
README.md: 7 brokendocs/links repointed; Documentation section restructured into Concepts / Guides / Reference.CHANGELOG.mdmigration links repointed todocs/archive/migrations/.libs/beacon/src/beacon/{core/dependencies,domains/distribution}/...pyMIGRATION_DOC_URLconstants updated; tests updated.openspec/specs/{agent-requires-manifest,artifact-dependency-resolution}/spec.mdupdated.Phase F — restructure (commit 6)
Iterative review pass on top of Phases A–D:
philosophy(moved from concepts/) +skills(merged what-is-a-skill + bundled-skills framing, reframed as 'thin skills, fat tools' / intermediate state).interactive-adoption.md+syncing.mdconsolidated into a singleadopting-artifacts.mdpresenting interactive vs declarative paths.creating-skills,creating-knowledge-and-contexts,creating-agents.contribute-warehousemoved toreference/(it is reference, not a flow guide).team-collaboration.md(covered by symlink/sync/adoption pages),spec-driven-development.md(out of scope; openspec mentioned where relevant).Phase G — audit pass (commit 7)
Critical-read audit of the post-restructure site, then targeted trimming:
concepts/specs-vs-artifacts.md(205-line essay),concepts/design-decisions.md(one-decision stub),guides/connecting-projects.md(covered by Quickstart),guides/advanced-patterns.md(duplicatescli.mdandbeacon-yaml.md),tutorials/first-contribution.md(80% duplicatedday-to-day-workflow.md; unique 'stray edit' beat folded into the discard section). Tutorials nav section gone.artifacts/contexts/knowledge/...→artifacts/knowledge/...); broken Python-standards link inwarehouse-lint/github-actions.md.abc sync --yesandabc warehouse contribute --paths(both in code, undocumented).What stays in
docs/after this PRdocs/archive/— historical design notes + migration records (preserved for external link resolution).docs/contributing/— agent-facing contribution material (moved back fromsite-docs/contributing/so AGENTS.md flows can reference it).docs/screenshots/— in-use UI assets.Site structure (after merge)
Test plan
mkdocs buildgreen throughout all phases (smoke-tested locally on :8765 between every commit)site-docs/(rg 'PER-[0-9]' site-docs/empty)site-docs/,mkdocs.yml, orREADME.mduv run pytest libs/beacon/tests/unit -q→ green at Phase E baseline (commits 6–7 are docs-only; no Python touched)design/philosophy.mdagainst the legacyagentic-warehouse-design.mdin git history — confirm no important framing was droppedCONTRIBUTING.mdstill works as a standalone GitHub-rendered onboarding doc