The landing page still opened with "archied is a resident daemon that polls a
forge", which is wrong twice over. A deployment is a set of contracted services,
not one process, and a forge is one event source among several: signed webhooks
from any sender and chat-channel messages reach the same playbook routing that a
GitHub or Gitea issue does. GitHub/Gitea was the first case, not the shape of the
product.
The intro now leads with the event path (event -> playbook -> workflow in an
isolated worktree) and says outright that sources, their fields, and the workflows
they reach are configuration rather than code. "What runs where" names the actual
services and which contract each owns. The stray "Work arrives as events." line
went with it, since the intro now states that.
Claims are held to what ships: module actions load and type-check but are not
dispatched yet, so the page promises one outcome per event, not a fan-out.
The intro stated per-task sandbox and credential isolation and daemon-owned
git to a reader who has no reason to act on it. Keep the event framing; the
enforcement detail stays in What runs where and ARCHITECTURE.md.
Regenerate docs/data/generated/docs.json with task docs:artifact.
The landing page opened by defining archied against a category the reader
never raised, then listed security features. State what the daemon does
and who owns git operations; drop the contrast.
Adds an mkdocs.yml, a landing page, and `task docs:site` / `task docs:serve`.
Deliberately hosting-agnostic: MkDocs is the same input Backstage TechDocs
consumes, so choosing where this lands later costs nothing.
exclude_docs holds back four subtrees, since everything under docs/ would
otherwise be published. archive/ is superseded design and would compete with
the current architecture for a reader's attention; inspiration/ discusses
other products by name; prds/ are open decisions rather than settled design;
github-token.md is credential setup. One PRD is let back through because
architecture/migration-decisions.md links to it three times, and a page
excluded out from under a live link is just a 404 with extra steps.
No nav block. MkDocs derives it from the directory layout, so a new page
under docs/architecture/ publishes without a second edit, and there is no
hand-maintained tree to drift against the repository.
Builds --strict, so a dead internal link fails rather than ships.
The docs site was never published: GitHub Pages is not configured for this
repository, so the workflow built and uploaded a site nobody served. docs/ is
repository documentation — Markdown read in the repository, an editor, or the
forge's file view — and does not need a renderer.
Removed:
- docs/.vitepress/config.mts, docs/package.json, docs/pnpm-lock.yaml (1620
lines), docs/pnpm-workspace.yaml
- docs/index.md (the site's landing page)
- .github/workflows/docs.yml (pnpm install, VitePress build, Pages deploy)
- the docs build-artefact ignores from .gitignore
Kept and corrected:
- docs/prds/01-project-management.md linked its decision documents with
VitePress root-absolute paths (/architecture/...), which only resolve under a
site build. Repointed to repository-relative paths.
- docs/architecture/generated-documentation.md named VitePress as the renderer
throughout. Now records the renderer and publishing surface as an open
decision, with the consequences stated: reference pages unrendered, no link
checker, no authoring server. Also corrected three claims that were never
true — the docsgen all/check subcommands and the docs:* tasks do not exist,
and no pre-commit hook is installed.
- .agents skills: build-and-env and docs-and-writing no longer describe a docs
site to build; the diagnostics scripts drop .vitepress skip rules and the
dead github_docs_build scan.
Generated output is unchanged: docs/data/generated/contracts.json and the
docsgen toolchain are untouched, and tools/ remains its own module.
Fold the old docs/ into the VitePress site and rename docs-2 -> docs.
The 12 architecture PRDs become first-class pages at docs/architecture/
with sidebar nav, rather than being buried under an archive path.
Historical material stays at docs/archive/. Rewrites every docs-2 and
docs/prds/architecture reference across the repo. Site builds clean.