chore(docs): remove the VitePress site and its build step

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.
This commit is contained in:
sam committed 2026-09-12 01:01:12 +10:00
1 parent 03afd2e8ad
commit de150f2068
15 files changed
+164 -2000

No files matched your search

+16 -20
View File
@@ -1,6 +1,6 @@
--- ---
name: archie-build-and-env name: archie-build-and-env
description: Recreate, inspect, and troubleshoot Archie Core's development, build, test, documentation, and container toolchains. Use when onboarding a checkout; diagnosing Go, Task, golangci-lint, gofumpt, pnpm, VitePress, Docker/Compose, NATS, GPG, cache, temporary-directory, listener, or network failures; comparing local work with repository automation; or proving which build surfaces a command actually covers. Load this before running task check in an unfamiliar or restricted environment because that gate rewrites files and omits several independent surfaces. description: Recreate, inspect, and troubleshoot Archie Core's development, build, test, documentation, and container toolchains. Use when onboarding a checkout; diagnosing Go, Task, golangci-lint, gofumpt, Docker/Compose, NATS, GPG, cache, temporary-directory, listener, or network failures; comparing local work with repository automation; or proving which build surfaces a command actually covers. Load this before running task check in an unfamiliar or restricted environment because that gate rewrites files and omits several independent surfaces.
--- ---
# Build and verify the Archie environment # Build and verify the Archie environment
@@ -18,7 +18,7 @@ All volatile observations are snapshots from **2026-07-28**.
| Repository root | Directory containing `go.mod`, `Taskfile.yml`, and `CLAUDE.md`. | | Repository root | Directory containing `go.mod`, `Taskfile.yml`, and `CLAUDE.md`. |
| Runtime module | Root Go module `github.com/samcharles93/archie-core`. | | Runtime module | Root Go module `github.com/samcharles93/archie-core`. |
| Tools module | Independent nested Go module under `tools/`. | | Tools module | Independent nested Go module under `tools/`. |
| Docs site | pnpm/VitePress project under `docs/`. | | Docs | Markdown under `docs/`, read directly; no build, no renderer. |
| Cold cache | Dependency cache not yet containing required modules/packages. | | Cold cache | Dependency cache not yet containing required modules/packages. |
| Restricted sandbox | May allow file reads but deny loopback listeners, container engine, or writes to default caches. | | Restricted sandbox | May allow file reads but deny loopback listeners, container engine, or writes to default caches. |
@@ -36,14 +36,14 @@ task --list
go version go version
go env GOTOOLCHAIN GOVERSION GOOS GOARCH CGO_ENABLED GOTMPDIR GOCACHE GOMODCACHE go env GOTOOLCHAIN GOVERSION GOOS GOARCH CGO_ENABLED GOTMPDIR GOCACHE GOMODCACHE
task --version; gofumpt -version; golangci-lint version task --version; gofumpt -version; golangci-lint version
node --version; pnpm --version; npm --version node --version; npm --version # UI only; docs need no Node toolchain
docker --version; docker compose version docker --version; docker compose version
git --version; gpg --version git --version; gpg --version
``` ```
Classify a missing command as an environment prerequisite. Bootstrap (verified Classify a missing command as an environment prerequisite. Bootstrap (verified
2026-07-28): Go ≥ 1.26.3, Task ≥ 3.x, gofumpt (unpinned), golangci-lint v2 2026-07-28): Go ≥ 1.26.3, Task ≥ 3.x, gofumpt (unpinned), golangci-lint v2
(unpinned), Node 24.x + pnpm ≥ 10. (unpinned), Node 24.x for the `ui/` frontend.
| Surface | Repository declaration | Installed snapshot | Interpretation | | Surface | Repository declaration | Installed snapshot | Interpretation |
|---|---|---|---| |---|---|---|---|
@@ -52,9 +52,7 @@ Classify a missing command as an environment prerequisite. Bootstrap (verified
| Task | Taskfile schema `version: "3"` | Task 3.48.0 | Installed version is environment fact. | | Task | Taskfile schema `version: "3"` | Task 3.48.0 | Installed version is environment fact. |
| gofumpt | Used by `task fmt`; `@latest` install | v0.7.0 | Unpinned. | | gofumpt | Used by `task fmt`; `@latest` install | v0.7.0 | Unpinned. |
| golangci-lint | v2 config in `.golangci.yml`; `@latest` install | 2.12.2 | Use v2 CLI; exact release unpinned. | | golangci-lint | v2 config in `.golangci.yml`; `@latest` install | 2.12.2 | Use v2 CLI; exact release unpinned. |
| Node | Docs CI `node-version: latest` | 24.18.0 | No `engines`/`packageManager` field. | | Node | `ui/` frontend build | 24.18.0 | No `engines`/`packageManager` field. Docs need no Node. |
| pnpm | Docs CI major 10 | 11.15.1 | Prefer CI's major 10. |
| VitePress | `^1.6.4`, locked to 1.6.4 | Resolved by `pnpm-lock.yaml` | Install with frozen lockfile. |
| Containers | Compose commands in `Taskfile.yml` | Podman-backed, unusable in this sandbox | Verify CLI, Compose plugin, daemon/socket separately. | | Containers | Compose commands in `Taskfile.yml` | Podman-backed, unusable in this sandbox | Verify CLI, Compose plugin, daemon/socket separately. |
## Prepare writable caches in a restricted sandbox ## Prepare writable caches in a restricted sandbox
@@ -115,9 +113,9 @@ golangci-lint run ./...
| `task clean` | Recursively removes `bin/`; destructive. | | `task clean` | Recursively removes `bin/`; destructive. |
| `task docker-build` | `docker compose build agent` only. | | `task docker-build` | `docker compose build agent` only. |
`task check` is the definitive gate but omits `task lint`, race tests, `tools/` `task check` is the definitive gate but omits `task lint`, race tests, and the
module, docs generation drift, and VitePress build. Run only in authorized `tools/` module. It has no docs step: there is no documentation build to omit.
writable worktree. For read-only preview: `gofumpt -l .`. Run only in authorized writable worktree. For read-only preview: `gofumpt -l .`.
## Verify the tools module separately ## Verify the tools module separately
@@ -142,18 +140,17 @@ cmp --silent docs/data/generated/contracts.json /tmp/archie-core-contracts.json
2026-07-28 run wrote 10 schemas; comparison passed. Planned `docsgen all` and 2026-07-28 run wrote 10 schemas; comparison passed. Planned `docsgen all` and
`docsgen check` do **not** exist yet. `docsgen check` do **not** exist yet.
## Recreate and build the docs site ## Documentation needs no build
```bash `docs/` is Markdown read directly in the repository, an editor, or the forge's
pnpm --dir docs install --frozen-lockfile file view. Nothing builds, renders, or publishes it.
pnpm --dir docs build
```
Git tracks 237 `docs/node_modules` symlink entries (commit `308c199`): The VitePress site (`docs/.vitepress/`, `docs/package.json`, the pnpm lockfile),
its landing page, and `.github/workflows/docs.yml` were removed on 2026-09-12 as
an unnecessary build step. Git no longer tracks any `docs/node_modules` entries.
```bash Do not `pnpm install` under `docs/`; it has no package manifest. See
git ls-files -s 'docs/node_modules/**' | awk '$1 == "120000" {count++} END {print count+0}' `docs/architecture/generated-documentation.md`, "Rendering and publishing".
```
Commit `4cb0577` cleaned up accidentally committed `.gotmp`; `.gotmp/` now ignored. Commit `4cb0577` cleaned up accidentally committed `.gotmp`; `.gotmp/` now ignored.
@@ -205,6 +202,5 @@ env GIT_CONFIG_GLOBAL=/dev/null go test ./internal/worktree/... ./internal/workt
| Build | `go build -o /tmp/... ./cmd/archied` and `cmd/archie-agent` | Both passed on 2026-07-28. | | Build | `go build -o /tmp/... ./cmd/archied` and `cmd/archie-agent` | Both passed on 2026-07-28. |
| Tools tests | `go -C tools test ./... -count=1` | Passed on 2026-07-28. | | Tools tests | `go -C tools test ./... -count=1` | Passed on 2026-07-28. |
| Generated contract parity | Temp docsgen output + `cmp --silent` | Passed for 10 schemas. | | Generated contract parity | Temp docsgen output + `cmp --silent` | Passed for 10 schemas. |
| Docs install/build | `pnpm --dir docs install --frozen-lockfile` then `pnpm build` | Blocked by restricted network. |
| Container build | `task docker-build` | Not verified in restricted environment. | | Container build | `task docker-build` | Not verified in restricted environment. |
| Repository gate | `task check` | Non-green; skillscript failure in root suite. | | Repository gate | `task check` | Non-green; skillscript failure in root suite. |
@@ -264,13 +264,12 @@ func countSelectors(root string, fset *token.FileSet, references map[string]*ref
}) })
} }
func excludedDirectory(relative, name string) bool { func excludedDirectory(_, name string) bool {
switch name { switch name {
case ".git", ".claude", ".references", "node_modules", "vendor", ".gotmp": case ".git", ".claude", ".references", "node_modules", "vendor", ".gotmp":
return true return true
} }
return strings.HasPrefix(relative, "docs/.vitepress/cache") || return false
strings.HasPrefix(relative, "docs/.vitepress/dist")
} }
func fail(code int, format string, arguments ...any) { func fail(code int, format string, arguments ...any) {
@@ -52,10 +52,9 @@ scan_literal task_test taskfile 'go test|task:[[:space:]]+test' Taskfile.yml
scan_literal task_lint taskfile 'golangci-lint|task:[[:space:]]+lint' Taskfile.yml scan_literal task_lint taskfile 'golangci-lint|task:[[:space:]]+lint' Taskfile.yml
scan_literal task_race taskfile 'go test[^#\n]*-race|-race[^#\n]*go test' Taskfile.yml scan_literal task_race taskfile 'go test[^#\n]*-race|-race[^#\n]*go test' Taskfile.yml
scan_literal task_tools_module taskfile 'go -C tools|cd tools|task:[[:space:]]+tools' Taskfile.yml scan_literal task_tools_module taskfile 'go -C tools|cd tools|task:[[:space:]]+tools' Taskfile.yml
scan_literal task_docs taskfile 'docsgen|pnpm[^#\n]*build|docs:generate|docs:check' Taskfile.yml scan_literal task_docs taskfile 'docsgen|docs:generate|docs:check' Taskfile.yml
scan_literal github_go_gate github-workflows 'go test|go vet|go build|golangci-lint|task[[:space:]]+check' .github/workflows scan_literal github_go_gate github-workflows 'go test|go vet|go build|golangci-lint|task[[:space:]]+check' .github/workflows
scan_literal github_docs_build github-workflows 'pnpm[[:space:]]+build|vitepress[[:space:]]+build' .github/workflows
scan_literal gitea_go_gate gitea-workflows 'go test|go vet|go build|golangci-lint|task[[:space:]]+check' .gitea/workflows scan_literal gitea_go_gate gitea-workflows 'go test|go vet|go build|golangci-lint|task[[:space:]]+check' .gitea/workflows
scan_literal gitea_container_publish gitea-workflows 'docker build|docker push' .gitea/workflows scan_literal gitea_container_publish gitea-workflows 'docker build|docker push' .gitea/workflows
@@ -247,13 +247,12 @@ func main() {
} }
} }
func excludedDirectory(relative, name string) bool { func excludedDirectory(_, name string) bool {
switch name { switch name {
case ".git", ".claude", ".references", "node_modules", "vendor", ".gotmp": case ".git", ".claude", ".references", "node_modules", "vendor", ".gotmp":
return true return true
} }
return strings.HasPrefix(relative, "docs/.vitepress/cache") || return false
strings.HasPrefix(relative, "docs/.vitepress/dist")
} }
func moduleFor(relative string) string { func moduleFor(relative string) string {
+30 -20
View File
@@ -1,6 +1,6 @@
--- ---
name: archie-docs-and-writing name: archie-docs-and-writing
description: Maintain Archie's documentation of record and write durable architecture decisions, migration plans, parity matrices, incident and dead-end records, feature ownership and deprecation records, operational runbooks, and documentation reviews. Use when deciding where an Archie fact belongs; reconciling code with ARCHITECTURE.md, CLAUDE.md, docs/prds, docs/archive, generated contracts, or the docs VitePress site; changing tools/docsgen; documenting a feature so future maintainers can find its owners, consumers, invariants, superseded paths, deletion gates, evidence, and rollback; or checking documentation authority, drift, links, copied content, and source-artifact hygiene. description: Maintain Archie's documentation of record and write durable architecture decisions, migration plans, parity matrices, incident and dead-end records, feature ownership and deprecation records, operational runbooks, and documentation reviews. Use when deciding where an Archie fact belongs; reconciling code with ARCHITECTURE.md, CLAUDE.md, docs/prds, docs/archive, or generated contracts; changing tools/docsgen; documenting a feature so future maintainers can find its owners, consumers, invariants, superseded paths, deletion gates, evidence, and rollback; or checking documentation authority, drift, links, copied content, and source-artifact hygiene.
--- ---
# Maintain Archie documentation # Maintain Archie documentation
@@ -48,11 +48,9 @@ Verified on 2026-07-28:
| `CHANGELOG.md`, `CHANGELOG.archied.md`, `CHANGELOG.archie.md` | Component release-note index and packaged runtime inputs | Keep gateway and agent-runtime entries separate; `internal/releaseannounce` parses version headings | | `CHANGELOG.md`, `CHANGELOG.archied.md`, `CHANGELOG.archie.md` | Component release-note index and packaged runtime inputs | Keep gateway and agent-runtime entries separate; `internal/releaseannounce` parses version headings |
| `tools/docsgen` | Current, partial generator in nested `tools` Go module | Treat its flags and tests—not planned PRD commands—as executable truth | | `tools/docsgen` | Current, partial generator in nested `tools` Go module | Treat its flags and tests—not planned PRD commands—as executable truth |
| `docs/data/generated/contracts.json` | Current working-tree `GENERATED` output | Regenerate; never edit by hand | | `docs/data/generated/contracts.json` | Current working-tree `GENERATED` output | Regenerate; never edit by hand |
| `docs/` | Staging VitePress site | Do not treat rendered summary as architecture record | | `docs/` | Repository documentation only | Nothing builds, renders, or publishes it; Markdown is the artifact |
| `.github/workflows/docs.yml` | Current Pages build/deploy workflow | Builds the site; does not run Go setup, generator tests, or drift checking |
The repository root has no `README.md` or `CONTRIBUTING.md` as of 2026-07-28. The repository root has no `README.md` or `CONTRIBUTING.md` as of 2026-07-28.
`docs/README.md` is excluded by VitePress and contains copied Tau material.
## Choose one destination ## Choose one destination
@@ -71,7 +69,7 @@ The repository root has no `README.md` or `CONTRIBUTING.md` as of 2026-07-28.
| Unresolved migration question | `docs/architecture/migration-decisions.md` | | Unresolved migration question | `docs/architecture/migration-decisions.md` |
| Contributor protocol that must load before work | `CLAUDE.md` | | Contributor protocol that must load before work | `CLAUDE.md` |
| Runtime/API/config reference derivable from code | Domain-owned registry/type, then `tools/docsgen` output | | Runtime/API/config reference derivable from code | Domain-owned registry/type, then `tools/docsgen` output |
| User-facing staging site prose | `docs/`, linking back to authority | | Repository documentation prose | `docs/`, linking back to authority with repository-relative paths |
| Shipped release behavior | Matching component changelog; keep `CHANGELOG.md` as two-component index | | Shipped release behavior | Matching component changelog; keep `CHANGELOG.md` as two-component index |
| Superseded design retained for context | `docs/archive/`, with historical status | | Superseded design retained for context | `docs/archive/`, with historical status |
| Incident or rejected approach | `archie-failure-archaeology`'s chronology | | Incident or rejected approach | `archie-failure-archaeology`'s chronology |
@@ -158,32 +156,44 @@ cmp "$docs_tmp" docs/data/generated/contracts.json
Treat the PRD's `docsgen all`, `docsgen check`, and `task docs:*` commands as Treat the PRD's `docsgen all`, `docsgen check`, and `task docs:*` commands as
`APPROVED TARGET`. `APPROVED TARGET`.
## Maintain the VitePress staging site ## Store documentation as repository Markdown
`docs/` is Markdown read directly in the repository, an editor, or the forge's
file view. Nothing builds, renders, or publishes it. The VitePress site, its
package manifest and lockfile, its landing page, and
`.github/workflows/docs.yml` were removed on 2026-09-12 as an unnecessary build
step; the publishing surface is an open decision
(`docs/architecture/generated-documentation.md`, "Rendering and publishing").
| Surface | Current state | | Surface | Current state |
|---|---| |---|---|
| Package | `docs/package.json`; VitePress `^1.6.4`; pnpm lockfile resolves 1.6.4 | | Content | Markdown under `docs/`, including `docs/data/generated/contracts.json` |
| Site config | Archie title, local search, clean URLs, last-updated metadata, output at `.vitepress/dist` | | Links | Repository-relative (`../architecture/organisation.md`); no root-absolute links |
| Copied content | `docs/README.md` describes Tau and is excluded by `srcExclude` | | Build | None. There is no site, no dev server, no link checker, no Pages deploy |
| Workflow | Frozen-lockfile install, `pnpm build`, Pages artifact upload/deploy | | Nav | `docs/prds/01-project-management.md` |
| Missing gates | No Go setup, docsgen test, generator drift check, or root `task check` integration |
Because no build validates links, check them yourself or with a one-off script —
nothing catches a dead link for you:
```bash ```bash
pnpm --dir docs install --frozen-lockfile # every relative markdown link target that does not resolve
pnpm --dir docs build grep -rhoE '\]\([^)#]+' docs --include=*.md | sed -E 's/^\]\(//' | sort -u
``` ```
### Enforce source-artifact hygiene ### Enforce source-artifact hygiene
As of 2026-07-28, Git tracks 237 `docs/node_modules` symlink entries. Neither Git tracks no `node_modules` entries (verified 2026-09-12; the 237 `docs/`
`docs/node_modules` nor `docs/.vitepress/dist` is ignored by root `.gitignore`. symlinks recorded on 2026-07-28 are gone) and no VitePress output. A future
renderer must not reintroduce committed installs or build output.
```bash ```bash
git ls-files -s 'docs/node_modules/**' | awk '$1 == 120000 { count++ } END { print count + 0 }' git ls-files | grep -c node_modules # expect 0
git ls-files 'docs/.vitepress/dist/**' ls docs/package.json docs/pnpm-lock.yaml 2>&1 # expect: No such file
git check-ignore -v docs/node_modules docs/.vitepress/dist || true ls .github/workflows/ # expect deploy.yml only
rg -n -i 'tau|template|placeholder' docs --glob '!node_modules/**'
``` ```
Never stage dependency installs, VitePress output, generator scratch files, Historical mentions of VitePress in `docs/architecture/` are deliberate — they
record what was removed. A grep for the word alone is not a failure signal.
Never stage dependency installs, renderer output, generator scratch files,
credentials, absolute paths, wall-clock data, or machine-specific values. credentials, absolute paths, wall-clock data, or machine-specific values.
-68
View File
@@ -1,68 +0,0 @@
name: Deploy docs
on:
push:
branches: [main]
paths:
- "docs/**"
- "tools/**"
- ".github/workflows/docs.yml"
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: pages
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # full history - VitePress lastUpdated needs it
- uses: pnpm/action-setup@v6
with:
version: 10
- uses: actions/setup-node@v4
with:
node-version: latest
cache: pnpm
cache-dependency-path: docs/pnpm-lock.yaml
- uses: actions/cache@v4
with:
path: docs/.vitepress/cache
key: ${{ runner.os }}-vitepress-${{ hashFiles('docs/**', 'docs/pnpm-lock.yaml') }}
restore-keys: |
${{ runner.os }}-vitepress-
- name: Install dependencies
working-directory: docs
run: pnpm install --frozen-lockfile
- name: Build docs site
working-directory: docs
run: pnpm build
- uses: actions/configure-pages@v5
- uses: actions/upload-pages-artifact@v3
with:
path: docs/.vitepress/dist
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- id: deployment
uses: actions/deploy-pages@v4
-5
View File
@@ -11,11 +11,6 @@ task.json
config.production.toml config.production.toml
.gotmp/ .gotmp/
# Docs site build artefacts
node_modules/
.vitepress/cache/
.vitepress/dist/
# Scratch # Scratch
/tmp/ /tmp/
.crew/ .crew/
-47
View File
@@ -1,47 +0,0 @@
import { defineConfig } from "vitepress";
export default defineConfig({
title: "Archie",
description: "Documentation for the Archie personal agent platform.",
lastUpdated: true,
cleanUrls: true,
srcDir: ".",
srcExclude: ["README.md"],
outDir: ".vitepress/dist",
head: [["link", { rel: "icon", href: "/favicon.svg" }]],
themeConfig: {
logo: "/favicon.svg",
nav: [{ text: "Architecture", link: "/architecture/" }],
sidebar: {
"/architecture/": [
{
text: "Architecture",
items: [
{ text: "Overview", link: "/architecture/" },
{ text: "Repository Organisation", link: "/architecture/organisation" },
{ text: "Dependencies and Contracts", link: "/architecture/dependencies-and-contracts" },
{ text: "Agent System", link: "/architecture/agent-system" },
{ text: "Configuration", link: "/architecture/configuration" },
{ text: "Identity", link: "/architecture/identity" },
{ text: "Messaging and Work Intake", link: "/architecture/messaging-and-work-intake" },
{ text: "Plugins and Extensions", link: "/architecture/plugins-and-extensions" },
{ text: "Policy System", link: "/architecture/policy" },
{ text: "Safe Change and Recovery", link: "/architecture/safe-change-and-recovery" },
{ text: "Generated Documentation", link: "/architecture/generated-documentation" },
{ text: "Domain and Feature Review Procedure", link: "/architecture/package-review" },
{ text: "Migration Decisions", link: "/architecture/migration-decisions" },
],
},
],
},
search: {
provider: "local",
},
footer: {
message: "Built with VitePress.",
copyright: "Archie",
},
},
});
+92 -152
View File
@@ -1,7 +1,7 @@
# Generated Documentation and Documentation Site # Generated Documentation
**Status:** Initial generator and site scaffold in progress **Status:** Generator scaffold in place; renderer and publishing removed
**Date:** 2026-07-28 **Date:** 2026-07-28 (revised 2026-09-12)
**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73) **Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)
## Purpose ## Purpose
@@ -12,53 +12,53 @@ Archie's documentation-generation approach is:
source of truth for published contracts; source of truth for published contracts;
- a repository-local Go generator extracts and normalizes documentation data; - a repository-local Go generator extracts and normalizes documentation data;
- the generator writes deterministic JSON/data files and protocol schemas; - the generator writes deterministic JSON/data files and protocol schemas;
- VitePress data loaders, components, and templates render the generated data - the rendering and publishing surface is an **open decision** — the VitePress
into reference pages; site and its Pages deployment were removed on 2026-09-12 as an unnecessary
- GitHub Actions builds and publishes the static site. build step (see "Rendering and publishing" below).
Hugo is not part of the target architecture. Hugo is not part of the target architecture.
The documentation system is rooted at: The documentation system is rooted at:
```text ```text
.github/workflows/docs.yml
tools/ tools/
go.mod go.mod
go.sum go.sum
docsgen/ docsgen/
main.go main.go
docs/ docs/
.vitepress/ data/generated/
public/ public/schemas/
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
*.md *.md
``` ```
### VitePress site ### Rendering and publishing — OPEN
The `docs` site provides: Superseded 2026-09-12. The repository previously carried a VitePress site
(`docs/.vitepress/config.mts`, `docs/package.json`, a 1620-line
`docs/pnpm-lock.yaml`, `docs/pnpm-workspace.yaml`) built and deployed to GitHub
Pages by `.github/workflows/docs.yml`. It was removed as an unnecessary build
step: the published site was never stood up, and the Pages target is not
configured.
- VitePress 1.6.x with pnpm; `docs/` is now repository documentation only — markdown read in the repository,
- Markdown content at the site root; an editor, or a forge's file view. Nothing in the repository builds, renders, or
- repository-owned navigation and sidebar configuration; publishes it.
- local full-text search;
- clean URLs and last-updated metadata;
- build output under `.vitepress/dist`;
- GitHub Pages-compatible static output;
### GitHub Pages workflow The renderer for the generated `data/generated/*.json` is therefore **undecided**.
Consequences that follow, and their current state:
The workflow provides: | Concern | State after removal |
| --- | --- |
| Reference-page rendering | Undecided; `data/generated/contracts.json` is committed but unrendered |
| Internal link validation | Not enforced by any build; links are repository-relative (`../architecture/...`) and resolve on the filesystem |
| Generated-data drift detection | Unchanged — `docsgen check` compares committed output, independent of any renderer |
| Navigation/sidebar | The authoritative index is `docs/prds/01-project-management.md` |
| Local authoring server | None; read markdown directly |
- full-history checkout for VitePress `lastUpdated`; A future renderer MUST NOT reintroduce a dead-link-blind build: VitePress
- pinned pnpm major version; previously validated internal links during its production build, and no
- Node setup and pnpm caching; replacement currently does.
- VitePress cache reuse;
- frozen-lockfile installation;
- static build, artifact upload, and Pages deployment;
- serialized deployments without cancelling an in-progress publish.
## Single source of truth ## Single source of truth
@@ -121,7 +121,7 @@ docsgen all
docsgen check docsgen check
``` ```
- `data` writes the normalized JSON consumed by VitePress. - `data` writes the normalized JSON reference data.
- `asyncapi` writes protocol schemas and envelopes. - `asyncapi` writes protocol schemas and envelopes.
- `all` generates every committed artifact. - `all` generates every committed artifact.
- `check` generates into a temporary directory and fails on drift. - `check` generates into a temporary directory and fails on drift.
@@ -152,12 +152,6 @@ docs/
schemas/ schemas/
asyncapi-header.yaml asyncapi-header.yaml
archie.yaml archie.yaml
.vitepress/
config.mts
data/
reference.data.ts
theme/
components/
.tmp/ .tmp/
``` ```
@@ -173,10 +167,11 @@ manually. `.tmp/` is generator-owned, ignored, and never committed.
- source-to-data drift diagnostics; - source-to-data drift diagnostics;
- future external consumers. - future external consumers.
VitePress loads these files at build time through a typed `.data.ts` loader. These files are consumed at render time by whichever renderer is chosen (see
Pages and components import the loader's `data` export and render reference "Rendering and publishing"); the generator's contract is the committed JSON, not
views. Archie uses a custom loader because the authoritative inputs are JSON; any particular loader. A renderer reads `data/generated/*.json` directly — Archie
VitePress `createContentLoader` is reserved for Markdown content collections. does not use `createContentLoader`-style Markdown collection scanning, because
the authoritative inputs are JSON.
The final move from `docs/` to `docs/` occurs only after Archie content The final move from `docs/` to `docs/` occurs only after Archie content
contains intentional Archie pages and the current architecture documents have an contains intentional Archie pages and the current architecture documents have an
@@ -287,15 +282,15 @@ The first vertical slice proves the normalized model and deterministic JSON
serialization. Later categories reuse it rather than introducing serialization. Later categories reuse it rather than introducing
category-specific ad hoc output formats. category-specific ad hoc output formats.
### Step 5: render data with VitePress ### Step 5: render data (pending renderer decision)
Create typed data loaders, components, and page templates for the normalized Blocks on "Rendering and publishing" above. Once a renderer is chosen, it reads
data. The loaders watch `data/generated/*.json`, parse and validate the files, `data/generated/*.json`, validates it, and renders reference views.
and return serializable data at build time.
Handwritten top-level navigation remains explicit. Reference navigation and Navigation and routes derive from `catalog.json`; they MUST NOT be duplicated by
routes derive from `catalog.json`; they are not emitted as generated TypeScript hand in renderer configuration.
or duplicated manually in `.vitepress/config.mts`.
No renderer is chosen, so this step is unstarted.
### Step 6: implement deterministic drift checking ### Step 6: implement deterministic drift checking
@@ -318,125 +313,73 @@ Generation MUST exclude:
Two consecutive `docsgen all` runs MUST be byte-identical. Two consecutive `docsgen all` runs MUST be byte-identical.
### Step 7: adapt the VitePress site ### Step 7: renderer adaptation — blocked
Maintain Archie-specific configuration and content: Was "adapt the VitePress site". No renderer is chosen; this step is unstarted.
- site title and description; When a renderer is selected it MUST:
- repository, edit, and source links;
- navigation and sidebars;
- favicon, CNAME, and deployment base path;
- landing page and guides;
- protocol links;
- footer;
- embedded documentation expectations.
Retain: - read `data/generated/*.json` rather than re-deriving from source;
- validate internal links, with dead-link failures enabled (no blanket
ignore list);
- state its own local preview and build commands;
- keep `node_modules/` and any build output out of source control.
- local search; ### Step 8: developer commands
- clean URLs;
- last-updated metadata;
- repository-owned VitePress configuration;
- pnpm frozen-lockfile builds.
VitePress validates Markdown and internal links during its production build. No `docs:*` task exists. `Taskfile.yml` does not reference the generator, and
Dead-link failures MUST remain enabled; blanket `ignoreDeadLinks` is prohibited. `task check` does not run `docs:check`, so generated drift is currently ungated.
### Step 8: adapt developer commands The generator is run directly:
`Taskfile.yml` will expose:
```text
task docs:generate # go -C tools run ./docsgen all
task docs:check # go -C tools run ./docsgen check, then build VitePress
task docs:serve # generate, install if needed, then start VitePress dev
task docs:build # generate/check and create the production static site
```
Commands use explicit paths:
```sh ```sh
go -C tools run ./docsgen all --repo-root .. go -C tools run ./docsgen all --repo-root ..
go -C tools run ./docsgen check --repo-root .. go -C tools run ./docsgen check --repo-root ..
pnpm --dir docs install --frozen-lockfile
pnpm --dir docs dev
pnpm --dir docs build
``` ```
The final command syntax must match the implemented CLI, but these task names Wiring `docs:check` into `task check` is worth doing and does not depend on the
and responsibilities are fixed. renderer decision.
`task check` runs `docs:check`. Generated drift, invalid Markdown, dead links, ### Step 9: CI
or a failed VitePress build block completion.
### Step 9: adapt CI and Pages deployment The documentation workflow was deleted on 2026-09-12. No workflow builds, checks,
or publishes documentation. `deploy.yml` does not reference `docs/**`.
The workflow watches: Reintroducing CI for documentation requires the renderer decision first. Any
such workflow MUST check generated output and MUST NOT regenerate and silently
publish uncommitted differences.
```text ### Step 10: cutover — done, in reverse
.github/workflows/docs.yml
docs/**
tools/go.mod
tools/go.sum
tools/docsgen/**
authoritative domain registry and type paths
```
The build job: The site cutover is moot: the site was removed rather than published. The
generator's outputs (`docs/data/generated/`, `docs/public/schemas/`) remain
committed and are the durable artifacts.
1. checks out full history; Still standing from the original cutover list:
2. installs the repository's Go version;
3. runs `docsgen check`;
4. installs the pinned pnpm version;
5. installs the configured Node version;
6. restores pnpm and VitePress caches;
7. installs dependencies with the frozen lockfile;
8. builds VitePress;
9. uploads `docs/.vitepress/dist`.
The deploy job uses the required Pages permissions, environment, concurrency, - remove Markdown, examples, specs, generated schemas, and assets that do not
and artifact deployment flow. describe Archie;
CI MUST check generated output; it MUST NOT regenerate and silently publish
uncommitted differences.
### Step 10: remove non-source artifacts and cut over
Before treating the site as Archie documentation:
- keep `node_modules/` out of source control;
- keep `.vitepress/dist/` out of source control;
- ensure both paths are ignored;
- remove Markdown, examples, specs, generated schemas, and assets that do
not describe Archie;
- adapt retained content and prove it against Archie code; - adapt retained content and prove it against Archie code;
- update `docs.go` and its tests to embed only intentional runtime - update `docs.go` and its tests to embed only intentional runtime
documentation; documentation;
- decide which current `docs/prds` remain published architecture pages and which - decide which current `docs/prds` remain published architecture pages and which
remain repository-only planning documents; remain repository-only planning documents — all of them are repository-only
- rename `docs` to its final location; now, so the distinction is retired.
- update workflow, Taskfile, links, and embed paths atomically.
Documents MUST describe Archie before they are published. Documents MUST describe Archie. Publishing is a separate, undecided concern.
## Hook and CI policy ## Hook and CI policy
Generated documentation is committed. Generated documentation is committed.
The pre-commit hook: No pre-commit hook is installed in this repository, and no CI step runs the
generator. The policy below is the intended contract, currently unenforced:
1. detects authoritative definition or generator changes; 1. detects authoritative definition or generator changes;
2. runs `task docs:generate`; 2. runs the generator;
3. runs `task docs:check`; 3. runs `docsgen check`;
4. refuses the commit when generated changes are unstaged or validation fails. 4. refuses the commit when generated changes are unstaged or validation fails.
CI:
1. runs `task docs:check` without modifying committed output;
2. builds the static site;
3. publishes only from the approved branch or release;
4. never treats generated data as handwritten source.
A commit MUST NOT be created while generated documentation is stale. A commit MUST NOT be created while generated documentation is stale.
## Validation requirements ## Validation requirements
@@ -454,15 +397,14 @@ Generator tests cover:
- byte-identical repeated generation; - byte-identical repeated generation;
- check-mode diagnostics. - check-mode diagnostics.
Site validation covers: Repository-documentation validation covers:
- frozen dependency installation; - internal links resolve on the filesystem (repository-relative paths);
- VitePress production build;
- dead internal links;
- generated-data loader imports;
- expected output routes;
- absence of unrelated product names and URLs; - absence of unrelated product names and URLs;
- absence of committed build artifacts. - absence of committed build artifacts and installed dependencies.
Renderer validation (frozen dependency installation, production build, expected
output routes) is added with the renderer decision and is currently unenforced.
The root module remains free of generator-only dependencies. The root module remains free of generator-only dependencies.
@@ -475,20 +417,18 @@ The documentation migration is complete when:
- AsyncAPI output describes Archie; - AsyncAPI output describes Archie;
- required reference categories are generated as committed deterministic data; - required reference categories are generated as committed deterministic data;
- `catalog.json` matches the generated definitions and rendered routes; - `catalog.json` matches the generated definitions and rendered routes;
- VitePress components and templates render the generated data;
- two consecutive generations are byte-identical; - two consecutive generations are byte-identical;
- `docsgen check` detects changed, missing, and obsolete artifacts; - `docsgen check` detects changed, missing, and obsolete artifacts;
- VitePress contains only intentional Archie content;
- build artifacts and installed dependencies are absent from source control; - build artifacts and installed dependencies are absent from source control;
- `task docs:serve` supports local authoring; - `task docs:generate` and `task docs:check` work from a clean checkout;
- `task docs:build` produces the deployable site; - every document describes Archie and every internal link resolves.
- `task check` blocks stale or broken documentation;
- GitHub Pages publishes the verified VitePress artifact. Renderer-dependent criteria (rendered reference pages, local authoring server,
deployable build, published site) are removed pending the renderer decision.
## Implementation references ## Implementation references
- [VitePress getting started](https://vitepress.dev/guide/getting-started) - [GitHub-flavoured Markdown specification](https://github.github.com/gfm/) —
- [VitePress site configuration](https://vitepress.dev/reference/site-config) the dialect repository documentation is written in
- [VitePress local search](https://vitepress.dev/reference/default-theme-search) - [pnpm](https://pnpm.io/) — required only if a future renderer chooses a
- [VitePress deployment](https://vitepress.dev/guide/deploy) Node-based toolchain
- [VitePress CLI](https://vitepress.dev/reference/cli)
+8 -6
View File
@@ -434,12 +434,14 @@ packages migrate:
These shared mechanisms do not acquire ownership of domain meaning. Domains These shared mechanisms do not acquire ownership of domain meaning. Domains
continue to own their commands, events, policies, settings, and consequences. continue to own their commands, events, policies, settings, and consequences.
The copied Go `specgen` and VitePress documentation pipeline, output placement, The Go documentation generator, its output placement, and drift checking are
developer commands, drift checking, hook sequence, and CI sequence are defined defined in `generated-documentation.md`. The VitePress site and its Pages
in `generated-documentation.md`. Adapting the copied files, implementing deployment were removed on 2026-09-12 as an unnecessary build step; `docs/` is
Archie's normalized documentation model and page renderers, and cutting `docs` repository documentation only. The rendering and publishing surface is an open
over to its final location remain migration work rather than open product decision, and so are the renderer's page templates and any developer commands
architecture. or CI sequence that would accompany one. Adapting the generator and implementing
Archie's normalized documentation model remain migration work rather than open
product architecture.
### 8. Cutover sequence ### 8. Cutover sequence
-25
View File
@@ -1,25 +0,0 @@
---
layout: home
hero:
name: Archie
text: Personal agent platform
tagline: Durable agents, conversations, workflows, tools, and integrations.
image:
src: /favicon.svg
alt: Archie
actions:
- theme: brand
text: Architecture
link: /architecture/
features:
- title: Personal agents
details: Persistent assistants with their own identity, specialisation, and private memory.
- title: Conversations
details: Durable, branchable conversations across messaging channels.
- title: Workflows
details: Reusable, versioned behaviour definitions for structured and automated work.
- title: Extensible capabilities
details: Typed plugins, tools, channels, and infrastructure integrations.
---
-14
View File
@@ -1,14 +0,0 @@
{
"name": "archie-docs",
"type": "module",
"version": "0.0.0",
"private": true,
"scripts": {
"dev": "vitepress dev . --port 5174",
"build": "vitepress build .",
"preview": "vitepress preview ."
},
"devDependencies": {
"vitepress": "^1.6.4"
}
}
-1620
View File
File diff suppressed because it is too large. Load diff
-2
View File
@@ -1,2 +0,0 @@
allowBuilds:
esbuild: true
+13 -13
View File
@@ -35,23 +35,23 @@ The words **MUST**, **MUST NOT**, **SHOULD**, and **MAY** are normative.
| Scope | Authoritative document | | Scope | Authoritative document |
| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Repository layout, domains, composition, deployments, and optional material | [architecture/organisation.md](/architecture/organisation) | | Repository layout, domains, composition, deployments, and optional material | [architecture/organisation.md](../architecture/organisation.md) |
| Dependency direction, domain contracts, infrastructure, commands, events, and wire contracts | [architecture/dependencies-and-contracts.md](/architecture/dependencies-and-contracts) | | Dependency direction, domain contracts, infrastructure, commands, events, and wire contracts | [architecture/dependencies-and-contracts.md](../architecture/dependencies-and-contracts.md) |
| External configuration, runtime settings, and dissolution of `internal/config` | [architecture/configuration.md](/architecture/configuration) | | External configuration, runtime settings, and dissolution of `internal/config` | [architecture/configuration.md](../architecture/configuration.md) |
| Persistent actor identity, ownership, lifecycle, and attribution | [architecture/identity.md](/architecture/identity) | | Persistent actor identity, ownership, lifecycle, and attribution | [architecture/identity.md](../architecture/identity.md) |
| Agent definitions, workflows, workflow executions, tools, and worker boundaries | [architecture/agent-system.md](/architecture/agent-system) | | Agent definitions, workflows, workflow executions, tools, and worker boundaries | [architecture/agent-system.md](../architecture/agent-system.md) |
| Personal-assistant interactions, messaging channels, and optional promotion into durable work | [architecture/messaging-and-work-intake.md](/architecture/messaging-and-work-intake) | | Personal-assistant interactions, messaging channels, and optional promotion into durable work | [architecture/messaging-and-work-intake.md](../architecture/messaging-and-work-intake.md) |
| Shared policy evaluation and domain-owned policy semantics | [architecture/policy.md](/architecture/policy) | | Shared policy evaluation and domain-owned policy semantics | [architecture/policy.md](../architecture/policy.md) |
| Safe source/configuration changes, health supervision, and recovery | [architecture/safe-change-and-recovery.md](/architecture/safe-change-and-recovery) | | Safe source/configuration changes, health supervision, and recovery | [architecture/safe-change-and-recovery.md](../architecture/safe-change-and-recovery.md) |
| Plugin framework, plugin implementations, and extension isolation | [architecture/plugins-and-extensions.md](/architecture/plugins-and-extensions) | | Plugin framework, plugin implementations, and extension isolation | [architecture/plugins-and-extensions.md](../architecture/plugins-and-extensions.md) |
| Generated references, deprecations, and changelog generation | [architecture/generated-documentation.md](/architecture/generated-documentation) | | Generated references, deprecations, and changelog generation | [architecture/generated-documentation.md](../architecture/generated-documentation.md) |
| Remaining package destinations, data migrations, runtime cutover, and completion criteria | [architecture/migration-decisions.md](/architecture/migration-decisions) | | Remaining package destinations, data migrations, runtime cutover, and completion criteria | [architecture/migration-decisions.md](../architecture/migration-decisions.md) |
| Domain/feature research, design interview, and required handoff | [architecture/package-review.md](/architecture/package-review) | | Domain/feature research, design interview, and required handoff | [architecture/package-review.md](../architecture/package-review.md) |
## Deferred decisions ## Deferred decisions
The remaining package-placement, data-migration, shared-mechanics, process- The remaining package-placement, data-migration, shared-mechanics, process-
boundary, and cutover decisions are maintained in boundary, and cutover decisions are maintained in
[architecture/migration-decisions.md](/architecture/migration-decisions). [architecture/migration-decisions.md](../architecture/migration-decisions.md).
Each decision is made in its focused document after code-grounded review. Each decision is made in its focused document after code-grounded review.