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:
1 parent
19062a702d
commit
84b326940b
15 files changed
+164
-2000
No files matched your search
@@ -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 {
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
@@ -11,11 +11,6 @@ task.json
|
||||
config.production.toml
|
||||
.gotmp/
|
||||
|
||||
# Docs site build artefacts
|
||||
node_modules/
|
||||
.vitepress/cache/
|
||||
.vitepress/dist/
|
||||
|
||||
# Scratch
|
||||
/tmp/
|
||||
.crew/
|
||||
|
||||
@@ -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",
|
||||
},
|
||||
},
|
||||
});
|
||||
@@ -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
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
---
|
||||
@@ -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"
|
||||
}
|
||||
}
|
||||
Generated
-1620
File diff suppressed because it is too large.
Load diff
@@ -1,2 +0,0 @@
|
||||
allowBuilds:
|
||||
esbuild: true
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user