From 59ffcdf229483c684b13c9c66bfb1efec4447bb2 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Tue, 22 Sep 2026 13:24:23 +1000 Subject: [PATCH] docs(site): describe archie as an event-driven agent platform The landing page still opened with "archied is a resident daemon that polls a forge", which is wrong twice over. A deployment is a set of contracted services, not one process, and a forge is one event source among several: signed webhooks from any sender and chat-channel messages reach the same playbook routing that a GitHub or Gitea issue does. GitHub/Gitea was the first case, not the shape of the product. The intro now leads with the event path (event -> playbook -> workflow in an isolated worktree) and says outright that sources, their fields, and the workflows they reach are configuration rather than code. "What runs where" names the actual services and which contract each owns. The stray "Work arrives as events." line went with it, since the intro now states that. Claims are held to what ships: module actions load and type-check but are not dispatched yet, so the page promises one outcome per event, not a fan-out. --- docs/data/generated/docs.json | 2 +- docs/index.md | 32 ++++++++++++++++++++------------ 2 files changed, 21 insertions(+), 13 deletions(-) diff --git a/docs/data/generated/docs.json b/docs/data/generated/docs.json index 69fe72932..4d13aa7b6 100644 --- a/docs/data/generated/docs.json +++ b/docs/data/generated/docs.json @@ -4,7 +4,7 @@ "url": "/docs/", "title": "Archie", "section": "", - "body": "# Archie\n\nEvent Driven Agentic Automation.\n\n**archied** is a resident daemon. It polls a forge (GitHub, Gitea) for issues\nassigned or labelled to it, works each one in an isolated git worktree through a\nrouted workflow, and opens a pull request for human review.\n\nWork arrives as events.\n\n## Start here\n\n- [First playbook](/docs/guides/first-playbook/) walks through getting one piece of\n work from an issue to a pull request.\n- [Architecture](/docs/architecture/) is the authority for settled design:\n the package map, the workflow engine, the task lifecycle, and the invariants\n that hold the whole thing together.\n\n## What runs where\n\nA deployment is one daemon plus the processes it talks to. The State Store is a\nstandalone process and owns the database outright; the daemon and gateway never\nopen it directly. Agents execute in containers that receive a task-scoped\ncredential, issued per task and revoked when the worktree is handed back.\n\nConfiguration lives at `${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`.\nNothing in a working tree is load-bearing at runtime.\n\n## A note on these docs\n\nThis site is generated from the `docs/` directory of the\n[archie-core repository](https://github.com/samcharles93/archie-core) on every\nchange to `main`. The repository is the source; this site is a view of it. If\nthe two ever disagree, the repository is right.\n" + "body": "# Archie\n\nEvent Driven Agentic Automation.\n\nArchie is an agent platform that reacts to events. A forge issue, a signed\nwebhook from any app you run, a message in a chat channel: each arrives as an\nevent, a playbook decides what a matching event sets off, and the work happens\nin an isolated git worktree. GitHub and Gitea issues were the first case. A\nforge is now one event source among several, and a pull request one outcome\namong several.\n\nNothing about that path is wired to a particular forge, channel, or sender.\nSources, the fields they carry, and the workflows they reach are configuration\nyou add without touching code or restarting anything.\n\n## Start here\n\n- [First playbook](/docs/guides/first-playbook/) points an external app's webhook\n at archie, maps the fields of a real payload, and binds them to a workflow.\n- [Architecture](/docs/architecture/) is the authority for settled design:\n the domain boundaries, the workflow engine, the task lifecycle, and the\n invariants that hold the whole thing together.\n\n## What runs where\n\nA deployment is a set of services, each owning one typed contract. The Gateway\nserves conversation turns and sessions, the Messaging Service runs the\nchannels, the State Store owns the database outright, the dashboard is its own\nprocess, and `archied` admits work and drives each task through its workflow.\ngRPC carries the synchronous calls between them; NATS carries asynchronous\nfan-out. Agents execute in containers that receive a task-scoped credential,\nissued per task and revoked when the worktree is handed back.\n\nConfiguration lives at `${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`.\nNothing in a working tree is load-bearing at runtime.\n\n## A note on these docs\n\nThis site is generated from the `docs/` directory of the\n[archie-core repository](https://github.com/samcharles93/archie-core) on every\nchange to `main`. The repository is the source; this site is a view of it. If\nthe two ever disagree, the repository is right.\n" }, { "url": "/docs/architecture/", diff --git a/docs/index.md b/docs/index.md index aaeb664ab..904a541ee 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,26 +2,34 @@ 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. +Archie is an agent platform that reacts to events. A forge issue, a signed +webhook from any app you run, a message in a chat channel: each arrives as an +event, a playbook decides what a matching event sets off, and the work happens +in an isolated git worktree. GitHub and Gitea issues were the first case. A +forge is now one event source among several, and a pull request one outcome +among several. -Work arrives as events. +Nothing about that path is wired to a particular forge, channel, or sender. +Sources, the fields they carry, and the workflows they reach are configuration +you add without touching code or restarting anything. ## Start here -- [First playbook](guides/first-playbook.md) walks through getting one piece of - work from an issue to a pull request. +- [First playbook](guides/first-playbook.md) points an external app's webhook + at archie, maps the fields of a real payload, and binds them to a workflow. - [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. + the domain boundaries, 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. +A deployment is a set of services, each owning one typed contract. The Gateway +serves conversation turns and sessions, the Messaging Service runs the +channels, the State Store owns the database outright, the dashboard is its own +process, and `archied` admits work and drives each task through its workflow. +gRPC carries the synchronous calls between them; NATS carries asynchronous +fan-out. 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.