diff --git a/.gitignore b/.gitignore index bc0435b60..3de0bb12e 100644 --- a/.gitignore +++ b/.gitignore @@ -48,3 +48,6 @@ config.production.toml .local/ __pycache__/ *.pyc + +# MkDocs build output (task docs:site) +/site/ diff --git a/Taskfile.yml b/Taskfile.yml index 4f103d5c8..31325af9a 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -129,6 +129,23 @@ tasks: happily report last week's tree against today's code. cmds: - python3 tools/reachaudit/reachaudit.py --repo . {{.CLI_ARGS}} + docs:site: + desc: "Build the documentation site into ./site (MkDocs). --strict, so a dead internal link fails the build." + summary: | + Publishes docs/ minus the subtrees held back in mkdocs.yml's + exclude_docs. Requires mkdocs-material: + + pip install --user mkdocs-material + + Distinct from docs:check, which verifies the generated contract data + rather than the site. + cmds: + - mkdocs build --strict + + docs:serve: + desc: "Serve the documentation site locally with live reload on :8000." + cmds: + - mkdocs serve ui:deps: desc: Install the dashboard's node dependencies (ui/node_modules is gitignored) diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..e037101a0 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,35 @@ +# Archie + +Event Driven Agentic Automation. + +**archied** is a resident daemon. It polls a forge (GitHub, Gitea) for issues +assigned or labelled to it, works each one in an isolated git worktree through a +routed workflow, and opens a pull request for human review. + +It is not a chat wrapper around a repository. Work arrives as events, each task +runs in its own sandbox with its own credentials, and the model never runs git. + +## Start here + +- [First playbook](guides/first-playbook.md) walks through getting one piece of + work from an issue to a pull request. +- [Architecture](architecture/index.md) is the authority for settled design: + the package map, the workflow engine, the task lifecycle, and the invariants + that hold the whole thing together. + +## What runs where + +A deployment is one daemon plus the processes it talks to. The State Store is a +standalone process and owns the database outright; the daemon and gateway never +open it directly. Agents execute in containers that receive a task-scoped +credential, issued per task and revoked when the worktree is handed back. + +Configuration lives at `${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`. +Nothing in a working tree is load-bearing at runtime. + +## A note on these docs + +This site is generated from the `docs/` directory of the +[archie-core repository](https://github.com/samcharles93/archie-core) on every +change to `main`. The repository is the source; this site is a view of it. If +the two ever disagree, the repository is right. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..570879c3a --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,65 @@ +site_name: Archie +site_description: Event Driven Agentic Automation +site_url: https://docs.offloaded.dev/ +repo_url: https://github.com/samcharles93/archie-core +edit_uri: edit/main/docs/ +copyright: Vectis Labs + +# Everything under docs/ is published to the public internet. These subtrees are +# held back deliberately, each for its own reason: +# archive/ superseded design. Publishing it competes with the current +# architecture for a reader's attention, which is the exact +# failure this repo already fights. +# inspiration/ research notes that discuss other products by name. +# prds/ open design decisions, not settled architecture. +# github-token setup notes about credentials. +# Widen this by deleting a line; nothing else needs to change. +exclude_docs: | + archive/ + inspiration/ + prds/* + !prds/ui-service-boundary.md + github-token.md + +theme: + name: material + favicon: public/favicon.svg + features: + - navigation.sections + - navigation.top + - navigation.instant + - content.code.copy + - content.action.edit + - search.suggest + - toc.follow + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/weather-night + name: Dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/weather-sunny + name: Light mode + +markdown_extensions: + - admonition + - attr_list + - tables + - toc: + permalink: true + - pymdownx.details + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.superfences + +plugins: + - search + +# No nav block on purpose. MkDocs derives the tree from the directory layout, so +# adding a page under docs/architecture/ publishes it without a second edit here. +# A hand-maintained nav is one more thing that goes stale against 600 commits a +# month.