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 19062a702d
commit 84b326940b
15 files changed
+164 -2000

No files matched your search

+16 -20
View File
@@ -1,6 +1,6 @@
---
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
@@ -18,7 +18,7 @@ All volatile observations are snapshots from **2026-07-28**.
| Repository root | Directory containing `go.mod`, `Taskfile.yml`, and `CLAUDE.md`. |
| Runtime module | Root Go module `github.com/samcharles93/archie-core`. |
| 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. |
| 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 env GOTOOLCHAIN GOVERSION GOOS GOARCH CGO_ENABLED GOTMPDIR GOCACHE GOMODCACHE
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
git --version; gpg --version
```
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
(unpinned), Node 24.x + pnpm ≥ 10.
(unpinned), Node 24.x for the `ui/` frontend.
| 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. |
| 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. |
| Node | Docs CI `node-version: latest` | 24.18.0 | No `engines`/`packageManager` field. |
| 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. |
| Node | `ui/` frontend build | 24.18.0 | No `engines`/`packageManager` field. Docs need no Node. |
| 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
@@ -115,9 +113,9 @@ golangci-lint run ./...
| `task clean` | Recursively removes `bin/`; destructive. |
| `task docker-build` | `docker compose build agent` only. |
`task check` is the definitive gate but omits `task lint`, race tests, `tools/`
module, docs generation drift, and VitePress build. Run only in authorized
writable worktree. For read-only preview: `gofumpt -l .`.
`task check` is the definitive gate but omits `task lint`, race tests, and the
`tools/` module. It has no docs step: there is no documentation build to omit.
Run only in authorized writable worktree. For read-only preview: `gofumpt -l .`.
## 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
`docsgen check` do **not** exist yet.
## Recreate and build the docs site
## Documentation needs no build
```bash
pnpm --dir docs install --frozen-lockfile
pnpm --dir docs build
```
`docs/` is Markdown read directly in the repository, an editor, or the forge's
file view. Nothing builds, renders, or publishes it.
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
git ls-files -s 'docs/node_modules/**' | awk '$1 == "120000" {count++} END {print count+0}'
```
Do not `pnpm install` under `docs/`; it has no package manifest. See
`docs/architecture/generated-documentation.md`, "Rendering and publishing".
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. |
| 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. |
| 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. |
| 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 {
case ".git", ".claude", ".references", "node_modules", "vendor", ".gotmp":
return true
}
return strings.HasPrefix(relative, "docs/.vitepress/cache") ||
strings.HasPrefix(relative, "docs/.vitepress/dist")
return false
}
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_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_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_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_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 {
case ".git", ".claude", ".references", "node_modules", "vendor", ".gotmp":
return true
}
return strings.HasPrefix(relative, "docs/.vitepress/cache") ||
strings.HasPrefix(relative, "docs/.vitepress/dist")
return false
}
func moduleFor(relative string) string {
+30 -20
View File
@@ -1,6 +1,6 @@
---
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
@@ -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 |
| `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/` | Staging VitePress site | Do not treat rendered summary as architecture record |
| `.github/workflows/docs.yml` | Current Pages build/deploy workflow | Builds the site; does not run Go setup, generator tests, or drift checking |
| `docs/` | Repository documentation only | Nothing builds, renders, or publishes it; Markdown is the artifact |
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
@@ -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` |
| Contributor protocol that must load before work | `CLAUDE.md` |
| 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 |
| Superseded design retained for context | `docs/archive/`, with historical status |
| 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
`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 |
|---|---|
| Package | `docs/package.json`; VitePress `^1.6.4`; pnpm lockfile resolves 1.6.4 |
| Site config | Archie title, local search, clean URLs, last-updated metadata, output at `.vitepress/dist` |
| Copied content | `docs/README.md` describes Tau and is excluded by `srcExclude` |
| Workflow | Frozen-lockfile install, `pnpm build`, Pages artifact upload/deploy |
| Missing gates | No Go setup, docsgen test, generator drift check, or root `task check` integration |
| Content | Markdown under `docs/`, including `docs/data/generated/contracts.json` |
| Links | Repository-relative (`../architecture/organisation.md`); no root-absolute links |
| Build | None. There is no site, no dev server, no link checker, no Pages deploy |
| Nav | `docs/prds/01-project-management.md` |
Because no build validates links, check them yourself or with a one-off script —
nothing catches a dead link for you:
```bash
pnpm --dir docs install --frozen-lockfile
pnpm --dir docs build
# every relative markdown link target that does not resolve
grep -rhoE '\]\([^)#]+' docs --include=*.md | sed -E 's/^\]\(//' | sort -u
```
### Enforce source-artifact hygiene
As of 2026-07-28, Git tracks 237 `docs/node_modules` symlink entries. Neither
`docs/node_modules` nor `docs/.vitepress/dist` is ignored by root `.gitignore`.
Git tracks no `node_modules` entries (verified 2026-09-12; the 237 `docs/`
symlinks recorded on 2026-07-28 are gone) and no VitePress output. A future
renderer must not reintroduce committed installs or build output.
```bash
git ls-files -s 'docs/node_modules/**' | awk '$1 == 120000 { count++ } END { print count + 0 }'
git ls-files 'docs/.vitepress/dist/**'
git check-ignore -v docs/node_modules docs/.vitepress/dist || true
rg -n -i 'tau|template|placeholder' docs --glob '!node_modules/**'
git ls-files | grep -c node_modules # expect 0
ls docs/package.json docs/pnpm-lock.yaml 2>&1 # expect: No such file
ls .github/workflows/ # expect deploy.yml only
```
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.
-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
.gotmp/
# Docs site build artefacts
node_modules/
.vitepress/cache/
.vitepress/dist/
# Scratch
/tmp/
.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
**Date:** 2026-07-28
**Status:** Generator scaffold in place; renderer and publishing removed
**Date:** 2026-07-28 (revised 2026-09-12)
**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)
## Purpose
@@ -12,53 +12,53 @@ Archie's documentation-generation approach is:
source of truth for published contracts;
- a repository-local Go generator extracts and normalizes documentation data;
- the generator writes deterministic JSON/data files and protocol schemas;
- VitePress data loaders, components, and templates render the generated data
into reference pages;
- GitHub Actions builds and publishes the static site.
- the rendering and publishing surface is an **open decision** — the VitePress
site and its Pages deployment were removed on 2026-09-12 as an unnecessary
build step (see "Rendering and publishing" below).
Hugo is not part of the target architecture.
The documentation system is rooted at:
```text
.github/workflows/docs.yml
tools/
go.mod
go.sum
docsgen/
main.go
docs/
.vitepress/
public/
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
data/generated/
public/schemas/
*.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;
- Markdown content at the site root;
- repository-owned navigation and sidebar configuration;
- local full-text search;
- clean URLs and last-updated metadata;
- build output under `.vitepress/dist`;
- GitHub Pages-compatible static output;
`docs/` is now repository documentation only — markdown read in the repository,
an editor, or a forge's file view. Nothing in the repository builds, renders, or
publishes it.
### 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`;
- pinned pnpm major version;
- Node setup and pnpm caching;
- VitePress cache reuse;
- frozen-lockfile installation;
- static build, artifact upload, and Pages deployment;
- serialized deployments without cancelling an in-progress publish.
A future renderer MUST NOT reintroduce a dead-link-blind build: VitePress
previously validated internal links during its production build, and no
replacement currently does.
## Single source of truth
@@ -121,7 +121,7 @@ docsgen all
docsgen check
```
- `data` writes the normalized JSON consumed by VitePress.
- `data` writes the normalized JSON reference data.
- `asyncapi` writes protocol schemas and envelopes.
- `all` generates every committed artifact.
- `check` generates into a temporary directory and fails on drift.
@@ -152,12 +152,6 @@ docs/
schemas/
asyncapi-header.yaml
archie.yaml
.vitepress/
config.mts
data/
reference.data.ts
theme/
components/
.tmp/
```
@@ -173,10 +167,11 @@ manually. `.tmp/` is generator-owned, ignored, and never committed.
- source-to-data drift diagnostics;
- future external consumers.
VitePress loads these files at build time through a typed `.data.ts` loader.
Pages and components import the loader's `data` export and render reference
views. Archie uses a custom loader because the authoritative inputs are JSON;
VitePress `createContentLoader` is reserved for Markdown content collections.
These files are consumed at render time by whichever renderer is chosen (see
"Rendering and publishing"); the generator's contract is the committed JSON, not
any particular loader. A renderer reads `data/generated/*.json` directly — Archie
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
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
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
data. The loaders watch `data/generated/*.json`, parse and validate the files,
and return serializable data at build time.
Blocks on "Rendering and publishing" above. Once a renderer is chosen, it reads
`data/generated/*.json`, validates it, and renders reference views.
Handwritten top-level navigation remains explicit. Reference navigation and
routes derive from `catalog.json`; they are not emitted as generated TypeScript
or duplicated manually in `.vitepress/config.mts`.
Navigation and routes derive from `catalog.json`; they MUST NOT be duplicated by
hand in renderer configuration.
No renderer is chosen, so this step is unstarted.
### Step 6: implement deterministic drift checking
@@ -318,125 +313,73 @@ Generation MUST exclude:
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;
- repository, edit, and source links;
- navigation and sidebars;
- favicon, CNAME, and deployment base path;
- landing page and guides;
- protocol links;
- footer;
- embedded documentation expectations.
When a renderer is selected it MUST:
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;
- clean URLs;
- last-updated metadata;
- repository-owned VitePress configuration;
- pnpm frozen-lockfile builds.
### Step 8: developer commands
VitePress validates Markdown and internal links during its production build.
Dead-link failures MUST remain enabled; blanket `ignoreDeadLinks` is prohibited.
No `docs:*` task exists. `Taskfile.yml` does not reference the generator, and
`task check` does not run `docs:check`, so generated drift is currently ungated.
### Step 8: adapt developer commands
`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:
The generator is run directly:
```sh
go -C tools run ./docsgen all --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
and responsibilities are fixed.
Wiring `docs:check` into `task check` is worth doing and does not depend on the
renderer decision.
`task check` runs `docs:check`. Generated drift, invalid Markdown, dead links,
or a failed VitePress build block completion.
### Step 9: CI
### 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
.github/workflows/docs.yml
docs/**
tools/go.mod
tools/go.sum
tools/docsgen/**
authoritative domain registry and type paths
```
### Step 10: cutover — done, in reverse
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;
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`.
Still standing from the original cutover list:
The deploy job uses the required Pages permissions, environment, concurrency,
and artifact deployment flow.
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;
- remove Markdown, examples, specs, generated schemas, and assets that do not
describe Archie;
- adapt retained content and prove it against Archie code;
- update `docs.go` and its tests to embed only intentional runtime
documentation;
- decide which current `docs/prds` remain published architecture pages and which
remain repository-only planning documents;
- rename `docs` to its final location;
- update workflow, Taskfile, links, and embed paths atomically.
remain repository-only planning documents — all of them are repository-only
now, so the distinction is retired.
Documents MUST describe Archie before they are published.
Documents MUST describe Archie. Publishing is a separate, undecided concern.
## Hook and CI policy
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;
2. runs `task docs:generate`;
3. runs `task docs:check`;
2. runs the generator;
3. runs `docsgen check`;
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.
## Validation requirements
@@ -454,15 +397,14 @@ Generator tests cover:
- byte-identical repeated generation;
- check-mode diagnostics.
Site validation covers:
Repository-documentation validation covers:
- frozen dependency installation;
- VitePress production build;
- dead internal links;
- generated-data loader imports;
- expected output routes;
- internal links resolve on the filesystem (repository-relative paths);
- 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.
@@ -475,20 +417,18 @@ The documentation migration is complete when:
- AsyncAPI output describes Archie;
- required reference categories are generated as committed deterministic data;
- `catalog.json` matches the generated definitions and rendered routes;
- VitePress components and templates render the generated data;
- two consecutive generations are byte-identical;
- `docsgen check` detects changed, missing, and obsolete artifacts;
- VitePress contains only intentional Archie content;
- build artifacts and installed dependencies are absent from source control;
- `task docs:serve` supports local authoring;
- `task docs:build` produces the deployable site;
- `task check` blocks stale or broken documentation;
- GitHub Pages publishes the verified VitePress artifact.
- `task docs:generate` and `task docs:check` work from a clean checkout;
- every document describes Archie and every internal link resolves.
Renderer-dependent criteria (rendered reference pages, local authoring server,
deployable build, published site) are removed pending the renderer decision.
## Implementation references
- [VitePress getting started](https://vitepress.dev/guide/getting-started)
- [VitePress site configuration](https://vitepress.dev/reference/site-config)
- [VitePress local search](https://vitepress.dev/reference/default-theme-search)
- [VitePress deployment](https://vitepress.dev/guide/deploy)
- [VitePress CLI](https://vitepress.dev/reference/cli)
- [GitHub-flavoured Markdown specification](https://github.github.com/gfm/) —
the dialect repository documentation is written in
- [pnpm](https://pnpm.io/) — required only if a future renderer chooses a
Node-based toolchain
+8 -6
View File
@@ -434,12 +434,14 @@ packages migrate:
These shared mechanisms do not acquire ownership of domain meaning. Domains
continue to own their commands, events, policies, settings, and consequences.
The copied Go `specgen` and VitePress documentation pipeline, output placement,
developer commands, drift checking, hook sequence, and CI sequence are defined
in `generated-documentation.md`. Adapting the copied files, implementing
Archie's normalized documentation model and page renderers, and cutting `docs`
over to its final location remain migration work rather than open product
architecture.
The Go documentation generator, its output placement, and drift checking are
defined in `generated-documentation.md`. The VitePress site and its Pages
deployment were removed on 2026-09-12 as an unnecessary build step; `docs/` is
repository documentation only. The rendering and publishing surface is an open
decision, and so are the renderer's page templates and any developer commands
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
-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 |
| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Repository layout, domains, composition, deployments, and optional material | [architecture/organisation.md](/architecture/organisation) |
| Dependency direction, domain contracts, infrastructure, commands, events, and wire contracts | [architecture/dependencies-and-contracts.md](/architecture/dependencies-and-contracts) |
| External configuration, runtime settings, and dissolution of `internal/config` | [architecture/configuration.md](/architecture/configuration) |
| Persistent actor identity, ownership, lifecycle, and attribution | [architecture/identity.md](/architecture/identity) |
| Agent definitions, workflows, workflow executions, tools, and worker boundaries | [architecture/agent-system.md](/architecture/agent-system) |
| Personal-assistant interactions, messaging channels, and optional promotion into durable work | [architecture/messaging-and-work-intake.md](/architecture/messaging-and-work-intake) |
| Shared policy evaluation and domain-owned policy semantics | [architecture/policy.md](/architecture/policy) |
| Safe source/configuration changes, health supervision, and recovery | [architecture/safe-change-and-recovery.md](/architecture/safe-change-and-recovery) |
| Plugin framework, plugin implementations, and extension isolation | [architecture/plugins-and-extensions.md](/architecture/plugins-and-extensions) |
| Generated references, deprecations, and changelog generation | [architecture/generated-documentation.md](/architecture/generated-documentation) |
| Remaining package destinations, data migrations, runtime cutover, and completion criteria | [architecture/migration-decisions.md](/architecture/migration-decisions) |
| Domain/feature research, design interview, and required handoff | [architecture/package-review.md](/architecture/package-review) |
| 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.md) |
| 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.md) |
| 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.md) |
| 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.md) |
| 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.md) |
| 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.md) |
## Deferred decisions
The remaining package-placement, data-migration, shared-mechanics, process-
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.