forked from jason/echo
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. |
|