forked from jason/echo
jason
f2bfd70dd4
The final phase of CHORUS-PLAN.md. Code- and doc-complete for group use; rc pends live deployment at chorusapi.mpm.to. - Repo README rewritten for CHORUS: group model (schema 5), concurrency posture, configuration, baked-build onboarding, layout, testing, 2.0 version history (ECHO history referenced at the fork tag). - Operator→member voice sweep across SKILL.md (incl. the trigger description, now group-aware), all references, 8 command docs, plugin README; member preferences / semantic layer / triage guidance describe the group model. - docs/ONBOARDING.md: member runbook — vault stand-up, per-member config, bake, deliver, self-onboarding first load, norms, offboarding. - docs/USAGE.md rewritten as the member usage guide. - New icon: chorus-icon.svg + 1024/512/64 PNGs (three voices, one center). - Removed ECHO-era assets (icons, spec PDF, perf briefs); ECHO planning docs retired to docs/history/. All preserved at echo-fork-point. - eval/README documents test_multimember.py. Manifest -> 2.0.0-rc.1; rebuilt chorus-memory.plugin. Verified: routing-sync, 25/25 unit, scaffold, 5 mock e2e suites, run_eval metrics green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
67 lines
4.4 KiB
Markdown
67 lines
4.4 KiB
Markdown
# CHORUS Member Onboarding
|
||
|
||
How to add a member to the group vault — from nothing to their first attributed write. The vault admin does steps 1–3; the member does step 4; the plugin does the rest.
|
||
|
||
## 0. One-time: stand up the vault (admin, once per group)
|
||
|
||
1. Run Obsidian with the **Local REST API** plugin on the backend host, pointed at an empty vault dedicated to the group.
|
||
2. Expose it at the deployment endpoint (**`https://chorusapi.mpm.to`**) behind the reverse proxy with a valid cert. Note the REST API's bearer key — this is the **vault key** every member's build will carry.
|
||
3. Configure your own machine (`chorus.py config set --group "…" --member "<your-id>" --endpoint "https://chorusapi.mpm.to" --key "…"`), then run `python3 scripts/bootstrap.py` — it stands up the folder tree, templates, group profile, group inbox, your member namespace, and the schema-5 marker. Follow with `sweep.py --apply` and `/chorus-doctor` to confirm green.
|
||
|
||
## 1. Create the member's config (admin)
|
||
|
||
Each member needs four values. Copy `chorus-memory.config.template.json` and fill it in:
|
||
|
||
```json
|
||
{
|
||
"group": "MPM",
|
||
"member": "alice",
|
||
"endpoint": "https://chorusapi.mpm.to",
|
||
"key": "<the vault key>"
|
||
}
|
||
```
|
||
|
||
`member` is a **kebab-case slug** (`^[a-z0-9][a-z0-9-]{0,31}$`) — it becomes the `author:` stamp on every one of their writes and their `_agent/members/alice/` namespace, so pick it once and keep it. `group` is the display name shared by everyone.
|
||
|
||
## 2. Bake their artifact (admin)
|
||
|
||
```bash
|
||
python build.py --bake-key --from alice-config.json --label alice
|
||
# -> dist/chorus-memory-<version>-alice.plugin
|
||
```
|
||
|
||
The baked artifact carries their member id, the endpoint, and the vault key inside the plugin, so it works on desktop **and** in every CoWork session with zero setup — no config file, no per-session paste. A complete baked set is authoritative and can't be shadowed by stale configs.
|
||
|
||
> **The artifact contains the live vault bearer token.** `dist/` is gitignored — deliver the file directly to that one member and never commit, push, or publish it. Offboarding/rotation = rotate the vault key, rebuild every member's artifact, redeliver.
|
||
|
||
## 3. Deliver (admin)
|
||
|
||
Send the member their `.plugin` file over a private channel. That file is their whole setup.
|
||
|
||
## 4. Install and start (member)
|
||
|
||
Install the plugin (Claude Code: `/plugin install <file>`; CoWork: add it to the session). Then just start a substantive session — the SessionStart hook runs `load`, and on that first load CHORUS **self-onboards** the member:
|
||
|
||
- creates `_agent/members/alice/` (preferences, current-context, inbox) and `_agent/sessions/alice/`,
|
||
- adds `- alice (joined YYYY-MM-DD)` to the group profile's `## Members` roster.
|
||
|
||
Nothing else to do. Sanity checks if wanted: `/chorus-doctor` (all green, member id shown with its source) and `load --all-members` (they appear in the roster).
|
||
|
||
## 5. First-session norms (member)
|
||
|
||
- Tell the agent a little about yourself when convenient — it lands in **your** `preferences.md` (`## Member` / `## Observations`). Preferences are group-visible by design; truly private material belongs in a personal vault, not CHORUS.
|
||
- Your quick captures go to **your** inbox; drop "someone should look at this" items in the **group inbox** (`inbox/captures/group.md`) as `- YYYY-MM-DD [you]: …`.
|
||
- Shared knowledge (projects, people, companies, decisions) is everyone's — the duplicate gate will stop you from creating a parallel note for something a teammate already tracks, and will tell you whose note it is.
|
||
- Never edit another member's `_agent/members/<id>/` namespace. Facts about a person as a person go in `resources/people/`.
|
||
|
||
## Troubleshooting
|
||
|
||
| Symptom | Meaning / fix |
|
||
|---|---|
|
||
| `NOT CONFIGURED` (exit 78) on load | The artifact isn't baked / config missing. Install the baked plugin, or `chorus.py config import <file>`. |
|
||
| `config set: --member must be a kebab-case slug` | Fix the member id — lowercase letters/digits/hyphens only. |
|
||
| Doctor: `member id configured — invalid` | Same as above; the config's `member` value isn't a valid slug. |
|
||
| Doctor: `vault reachable — FAIL` | Obsidian / Local REST API / the proxy at `chorusapi.mpm.to` isn't up. Not a config problem. |
|
||
| Load says `marker absent — vault not bootstrapped` | The vault itself was never stood up — run step 0.3 (admin). |
|
||
| `/chorus-health` reports `missing-author` | A note with `agent_written: true` lacks `author:` — someone hand-wrote it; add their member id. |
|