arizuko › concepts

concepts

A guided tour of how arizuko works, one idea at a time. Read it front to back the first time — each page builds on the one before it — or jump straight to the primitive you're stuck on.

How to take the tour

Concepts is a walkthrough, not a glossary. The order below is a learning arc: you meet the agent, watch a message reach it, then peel back one layer at a time — who's allowed to do what, how an agent proves who's calling, where its credentials and skills come from, and the surfaces it lives on. Each page is a single idea you can read in a minute or two, with one worked example from a real deployment.

Every page ends with a next link that walks this same order, so you can follow the tour with the pager and never lose your place. When you want the exhaustive grammar — every flag, every column, the full JID schema — each concept points you at its twin in reference. Concepts is the why and the shape; reference is the field list.

The tour

1. Primitives — the whole system in one page: six parts in a fixed order, and how every feature is those parts recombined. Read this first; the rest is detail.
2. How it’s built — arizuko is built the way it runs: specs, skills, file-based memory, and worktree subagents composing the same four layers.
3. The ant — the agent you talk to: a folder holding a persona, skills, memory, and secrets.
4. Routing — how an inbound message finds the right agent: one table mapping JIDs to folders.
5. Engagement — once a message lands, deciding whether to keep listening after a single mention.
6. Topics — scoping a strand of work into its own conversation inside one folder.
7. Onboarding — how a new group and its members are admitted: invites, the admission queue, SetupGroup.
8. Autoviv — how sub-groups and their agents come into being on first contact, without a manual step.
9. Personas — giving an agent its voice and standing instructions.
10. Auth — proving who is calling: OAuth, local login, account linking, one canonical sub.
11. Grants — what that principal is allowed to do, composed at spawn from tier, folder rules, and ACL.
12. Scopes — the folder hierarchy that grants speak in: who can see whom, where isolation begins.
13. Secrets — folder- and user-scoped credentials, and how they reach the container.
14. Skills — markdown instruction sets the agent loads on demand to extend what it can do.
15. Tasks — scheduled and recurring runs: cron, interval, one-shot, autonomous work.
16. Workflows — the discipline that makes multi-step jobs converge: free conversation, a strict opening, and one plan-of-record file.
17. Tokens — the no-login route tokens that let a public chat box or webhook reach an agent.
18. Web-native agents — the web surfaces a folder owns: a public page, embedded chat, form intake.
19. WebDAV — the file workspace, mountable from Finder, rclone, or curl.
20. Voice — voice in and out: Whisper transcribes, the agent decides when to speak back.
21. Slack pane — the Slack assistant sidebar: title, suggested prompts, pane context.
22. Addressing (JID) — the one typed address shape behind every chat and sender, across every adapter.

No setup commands here — those live in how-to. No exhaustive option tables — those live in reference. When you're ready to build, start with getting started.