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
03afd2e8ad
commit
de150f2068
15 files changed
+164
-2000
No files matched your search
@@ -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 {
|
||||||
|
|||||||
@@ -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.
|
||||||
@@ -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
|
config.production.toml
|
||||||
.gotmp/
|
.gotmp/
|
||||||
|
|
||||||
# Docs site build artefacts
|
|
||||||
node_modules/
|
|
||||||
.vitepress/cache/
|
|
||||||
.vitepress/dist/
|
|
||||||
|
|
||||||
# Scratch
|
# Scratch
|
||||||
/tmp/
|
/tmp/
|
||||||
.crew/
|
.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
|
**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)
|
|
||||||
@@ -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
|
||||||
|
|
||||||
|
|||||||
@@ -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 |
|
| 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.
|
||||||
Reference in new issue
Block a user