docs/README.md
Documentation library
For using Clankie, start with the public field guide: get started, everyday use, and DIY customization. This directory and the module READMEs hold the technical references.
Operate and configure
| Reference | Canonical scope |
|---|---|
| CLI | Headless commands, flags, output, and local/hosted modes |
| Integration | Approved commit batches, isolated gates, landing evidence and deploy holds |
| Console | Terminal interaction, workspaces, and launcher behavior |
| Distribution | Installed layout, runtime ownership, release build and verification |
| Fleet resources | Shared heavy permits, pressure admission and simulator ownership |
| Credentials | Secret identities, setup, rotation, and authority |
| Settings inventory | Every owner setting, its API and which surfaces set it (VUH-1813) |
| Always on | Host sleep, the keep-awake default, and the hosted-body alternative |
| Memory | Episodes, person facts, visibility, retention, and operator control |
| Bundled skills | Skill sources, discovery, and worker distribution |
| Local companion | Same-UID Mac pairing handoff and native loopback device session |
| Model keys | Paired-device API for model credentials and selection |
| Worker harness sign-in | Sign Claude Code and Codex workers into the owner's own subscriptions |
| Composer transcription | Paired-device recording, draft receipts and local/cloud boundaries |
| Worker access | Connected tools, native peer messages and manual grants |
| Tracker identity | Connected-account enforcement and remaining isolation work |
| Worker posts | One Linear app, worker names and portraits, compact handoffs |
| Discord media | Voice, music, Activity, Go Live, and screen-share differences |
| Activity sharing | Existing media, local/hosted controls, viewer admission and receipts |
| Remote Discord ingress | Authenticated sealed text and voice callbacks, independent of rollout |
| Desktop control | Native computer-use workflow and evidence limits |
| Rivals integration | External game extension: where it lives, how to install it, disabled status |
| Minecraft | Approved offline Java worlds, action evidence, play ownership and viewing |
| Linux self-hosting | Single-owner container deployment and supported capability set |
Understand and extend
Architecture owns the current system shape and request flows. Instruction and skill evals documents the isolated subscription runner. Product vocabulary defines chats, agents, rooms, history, sessions, and connections in the TUI. Contributing owns the source setup and checks.
Typechecking owns the compiler heap budget, program boundaries and retained diagnostics.
| Area | Owning reference |
|---|---|
| Service HTTP contract | OpenAPI, rendered as the API docs |
| Public wire contracts | packages/protocol |
| Native hire and message delivery | Harness adapters and current support |
| Harness discovery and transcripts | Agent hosts, transcripts |
| Project work tracking | Work items |
| Models | Provider resolution, catalog |
| Configuration | Settings, credential broker |
| Persona images | Owner image folders, voice descriptions and self-depiction |
| Images and video | Media connector |
| Game play | Play mind, rendered contract |
| Gameplay commentary | Play voice |
| Discord | Official bot, shared behavior, lab body |
| Native Discord media | Vox, client boundary |
| Activity media surface | Discord Activity |
| Remote device access | Relay, public network |
| Optional terminal integrations | Herdr plugin, Claude seat, Codex seat |
| Documentation and branding | Docs site, public marks |
| Public deployment | AWS boundary, docs hosting |
Proposals, decisions, and evidence
- Discord server roles define connected-server authority, fleet and project tracking.
- ADRs preserve decisions, amendments, and superseded designs. Read the current references above for operational instructions.
- Testing archive contains dated proofs and their limitations; quality gates define the recurring checks.
- Desktop runtime design is a dated proposal, not an implemented replacement for the desktop-control path.
- Clankie's own computer-use loop proposes direct native/provider loops, a shared hosted body and a manual comparison.
- Discord forum tracker view designs the two-way forum view of the built-in tracker (VUH-2531) and its slices.
- Discord surface review preserves the declined proposal to retire the Activity and the user-session lab body.
- Ruthless cut audit is a dated keep, cut or fold proposal under ADR 0203; later ADRs own the accepted decisions and current references own what ships.
Every fact has an owning source. The public site renders canonical command and API references rather than maintaining another copy. Its user guides explain what to do and link here for the mechanics.