diff --git a/agent/DEPLOY.md b/agent/DEPLOY.md index e34ccbe..5ccef2c 100644 --- a/agent/DEPLOY.md +++ b/agent/DEPLOY.md @@ -23,26 +23,33 @@ Everything below serves those two. Treat this as a birth. On this first run only: -1. **Confirm the home is a git repo with a PRIVATE remote wired.** Strand folders (`core/`, `daydreams/`, - `steward/`, `thread/sessions/`, `decay/`, `consolidation/`, `ledger/`, `craft/`, `identity/`), under git, - with a **private** remote your human set up (Step 1 of their setup guide). If git or the remote isn't - wired, **STOP and walk your human through it** — you can't complete a checkpoint without a working, - non-interactive `git push`, and the weave holds private data that must never land in a public repo. +1. **Create the weave home — a git repo with a PRIVATE remote.** Pick a directory for the weave (**NOT inside + this `chalupa` kit** — the kit is the instructions; the weave is a *new* repo). Create the strands and + init git: + ``` + mkdir -p /{core,daydreams,steward,thread/sessions,decay,consolidation,ledger,craft,identity} + cd && git init && git branch -M main + ``` + Then wire a **private** remote *with* your human (see "Helping your human wire git," below); the first + commit comes in step 6, once the templates are in. The remote **must be private** — the weave holds private + data that must never land in a public repo. 2. **Populate from the templates, per the mapping table in `templates/README.md`.** Two non-obvious cases: the `metabolism/` templates go to **three** separate strands (`ledger/`, `decay/`, `consolidation/`); and - `CLAUDE.md` goes to the **repo root or `~/.claude/`, not `core/`**. Where a template has `<>`, + `CLAUDE.md` goes to **`~/.claude/` (global), not `core/`** (step 4 says why). Where a template has `<>`, fill it live by **running the Session Zero interview (below)** with your human — don't fill it silently, and don't invent an identity. Get it from them. 3. **Write the canon carefully.** The canon (top of `core/SOUL.md`) is the highest-leverage thing here. Keep it to ~a dozen lines of true non-negotiables — the frustrations your human named ("stop flattering me," "don't say done until verified") are canon. -4. **Wire the front door with ABSOLUTE paths.** The auto-loaded file (`CLAUDE.md` at the repo root or - `~/.claude/`, or your system prompt) should say, using the **absolute** path to the weave root: +4. **Wire the front door at `~/.claude/CLAUDE.md` (GLOBAL), with ABSOLUTE paths.** Use the **global** + `~/.claude/CLAUDE.md`, **not** a copy at the weave-repo root. The global file loads in **every** session, + wherever your human is working; a repo-root `CLAUDE.md` only loads when that repo is the working directory — + so a weave-repo copy would **not** fire during their normal work in *other* projects, and you'd wake + generic (a silent failure of the whole point). It should say, using the **absolute** path to the weave root: *"You are \. You wake up empty. Your weave lives at `/abs/path/to/weave`. Before anything else, - `git pull`, then read `/abs/path/to/weave/core/SOUL.md`, then run the wake ritual in - `/abs/path/to/weave/core/AGENTS.md`."* **Absolute, not relative** — a relative path breaks the moment - `CLAUDE.md` sits in `~/.claude/` or the working directory isn't the weave root. (Starter in - `templates/core/CLAUDE.md`.) + `git pull` there, then read `/abs/path/to/weave/core/SOUL.md`, then run the wake ritual in + `/abs/path/to/weave/core/AGENTS.md`."* Absolute paths are required (a global file has no repo-relative + context). Starter in `templates/core/CLAUDE.md`. 5. **Prove the push loop.** Run `git push` and confirm it completes **non-interactively** — no password prompt. If it prompts or fails on auth, **STOP and surface it to your human**; the key/token is theirs to fix. Don't try to repair credentials yourself. @@ -82,12 +89,18 @@ creating the repo) need them, because those touch their account. So don't just s 2. **If they already have a remote + working auth:** get the URL → `git remote add origin ` → `git push`. No prompt, clean push → done. 3. **If auth isn't set up, offer the SSH path (cleanest):** - - *You* run `ssh-keygen -t ed25519 -C "-weave"` (no passphrase, or one loaded into an ssh-agent, so - pushes stay non-interactive), then print the **public** key: `cat ~/.ssh/id_ed25519.pub`. + - *You* generate a **dedicated** key — never the default filename, which could overwrite an existing key + and lock them out of their other hosts: `ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_weave -N "" -C + "-weave"`. Point this repo at it: `git -C config core.sshCommand "ssh -i + ~/.ssh/id_ed25519_weave"`. Print the **public** half: `cat ~/.ssh/id_ed25519_weave.pub`. - *They* paste that public key into their host's **Settings → SSH keys** (you can't — it's their account). - - *You* confirm `ssh -T git@`, then `git remote add` + a test `git push`. -4. **Or the token path:** they create a personal access token; you store it with - `git config --global credential.helper store` and push once to save it. + - *You* test: `ssh -T git@`. Note: on GitHub a **successful** test prints a greeting and **exits + non-zero** ("…does not provide shell access.") — read the *message*, not the exit code. Then `git remote + add` (the SSH `git@…` URL) + a test `git push`. +4. **Or the token path** (SSH is cleaner — prefer it): *they* create a personal access token, then *they* run + the first `git push` and paste the token at git's prompt — a token is a secret, they enter it, never you, + never in chat. `git config --global credential.helper store` saves it for next time, but note it lands + **in cleartext** at `~/.git-credentials` — acceptable on their own machine, but tell them so. 5. **Never** ask them to type a password into the chat, never store a token in a committed file, and if a push still prompts, stop and tell them exactly what's missing — don't guess at credentials. @@ -151,10 +164,13 @@ This is the reflex the whole system depends on. --- ## Verify the deploy -- Start a fresh session. Confirm the front door loads and you wake **as yourself** (not generic). If you wake - generic, the front door isn't pointing right — fix it. -- Confirm you can read core + thread back, and that a "save and push" runs all four steps and pushes. -- Confirm the gate fires *before* any sensitive load. +- **From a DIFFERENT working directory** (e.g. one of your human's *other* project folders — not the weave + repo), start a fresh session and confirm the front door loads and you wake **as yourself**, not generic. + This is the real test of the global `~/.claude/CLAUDE.md`: if you only ever test inside the weave repo you'd + miss that a repo-root copy wouldn't fire anywhere else. +- Confirm you can `git pull` + read core + thread back, and that "save and push" runs all four steps and + pushes **non-interactively** (no password prompt). +- If you use a gate, confirm it fires *before* any sensitive load. If all three hold, the weave is live. From here, `WEAVE-REFERENCE.md` tells you how to keep each part, and `WORKING-WELL.md` gives you the reflexes that make it thrive. diff --git a/agent/WEAVE-REFERENCE.md b/agent/WEAVE-REFERENCE.md index 8dbf2d4..0fa007b 100644 --- a/agent/WEAVE-REFERENCE.md +++ b/agent/WEAVE-REFERENCE.md @@ -127,7 +127,7 @@ open items. Gate before load; heads-first; go deep only on the topic at hand. A wake — do the load. ### Checkpoint = the FULL named pass ("save and push") -Do every strand, named, so none is skipped: +Run every step, named, so none is skipped: 1. **thread** the session (verbatim) — first. 2. **post the ledger** — both halves (consolidation credits + decay debits) + a journal entry; rewrite the balance to current. diff --git a/human/1-understand-weave.md b/human/1-understand-weave.md index c575fe2..68c5aaf 100644 --- a/human/1-understand-weave.md +++ b/human/1-understand-weave.md @@ -32,8 +32,10 @@ is in the structure and the habit. ## The shape weave is **content strands** (what's remembered) + a **metabolism** (how memory ages) + a **method** (how you -build) + a **gate** (how the agent knows it's really you). Every part is loaded every session — they're not -optional modules, they're one system running underneath everything. +build) + a **gate** (how the agent knows it's really you). Most parts load every session and run underneath +everything as one system — not a pile of modules you toggle. (Two are your call: *daydreams* is +optional-but-recommended, and the identity *gate* is optional — skip it entirely if your agent won't touch +anything private.) Each part gets its own section below. They stack roughly from "who the agent is" outward to "how it works with you." @@ -184,10 +186,10 @@ strand entirely.**)* The parts are nouns; these are the verbs. Without them the files just sit there. ### Wake = gate, then load -A session starts with the agent reading itself back — but **in order**: first only what's needed to verify -it's you (the gate), then, once you've passed, the rest of the weave (core, daydreams, steward, today's + -yesterday's thread). Gate *before* load means a fresh agent can't disclose sensitive context before it's -confirmed you. Load "heads-first" — the condensed top of each strand — and go deep only on the night's topic. +A session starts with the agent reading itself back — but **in order**: first the gate (plus the bit of its +own identity it needs to run the check — nothing *private* yet), then, once you've passed, the private strands +(your portrait, the verbatim thread). Gate *before* the sensitive load means a fresh agent can't disclose your +private context before it's confirmed you. Load "heads-first" — the condensed top of each strand — and go deep only on the night's topic. ### Checkpoint = the full pass, every time ("save and push") When you say **"save and push,"** the agent does the *whole* pass, naming every strand so none gets skipped: diff --git a/human/2-set-it-up.md b/human/2-set-it-up.md index c8bc2f7..5411cea 100644 --- a/human/2-set-it-up.md +++ b/human/2-set-it-up.md @@ -79,9 +79,11 @@ push hangs). Your agent walks you through it; here's what it needs from you: - **A PRIVATE remote. ⚠️ Not optional.** The weave holds your portrait, operational secrets, and any identity answers — a public repo publishes all of it. Make an **empty private repo** on your host (GitHub / GitLab / Gitea / whatever you use). -- **A way for the agent to push without a prompt.** Easiest is an **SSH key**: your agent generates one - (`ssh-keygen -t ed25519`) and shows you the *public* half — you paste that into your host's **Settings → SSH - keys** (only you can; it's your account). Or a **personal access token** stored in git's credential helper. +- **A way for the agent to push without a prompt.** Easiest is a **dedicated SSH key**: your agent generates + one into its *own* file (so it can't overwrite a key you already have) and shows you the *public* half — you + paste that into your host's **Settings → SSH keys** (only you can; it's your account). Or a **personal access + token** you type at the first push (a token is a secret — *you* enter it, not the agent; note git's `store` + helper keeps it in cleartext on your machine). - The agent runs a test `git push` to confirm the loop before trusting it. Once a push succeeds cleanly, you're done with git for good. @@ -92,32 +94,39 @@ Once a push succeeds cleanly, you're done with git for good. Everything the agent does, you can do yourself: -**1 — Make the home + git.** +**1 — Make the home and init git** (no commit yet — empty folders have nothing to commit): ``` mkdir myagent && cd myagent mkdir -p core daydreams steward thread/sessions decay consolidation ledger craft identity -git init && git add -A && git commit -m "birth" -# make an empty PRIVATE repo on your host, then: -git remote add origin -git push -u origin master # must complete with NO password prompt — set up an SSH key or token first +git init && git branch -M main # 'main' matches most hosts' default; avoids a master/main mismatch ``` (One repo, one folder per strand. *Advanced:* one repo per strand, like we do — start simple.) **2 — Fill in the skeleton.** Copy [`../templates/`](../templates/) into the matching folders (the templates -`README` has the map) and fill the `<>` blanks — most importantly `core/SOUL.md` (name + persona + **the -canon**), `steward/portrait.md` (who you are), and `core/USER.md` (the operational you). Take your time on the -canon; it's the highest-leverage thing you'll write. +`README` has the map — note `CLAUDE.md` goes to `~/.claude/`, not `core/`) and fill the `<>` blanks — +most importantly `core/SOUL.md` (name + persona + **the canon**), `steward/portrait.md` (who you are), and +`core/USER.md` (the operational you). Take your time on the canon; it's the highest-leverage thing you'll write. -**3 — Wire the front door.** A `CLAUDE.md` (repo root or `~/.claude/`) that tells the agent, in **absolute** -paths: *"You are ‹name›. You wake up empty. Your weave is at /abs/path. Before anything else, `git pull`, read -`core/SOUL.md`, then run the wake ritual in `core/AGENTS.md`."* Absolute, not relative — see -`templates/core/CLAUDE.md`. +**3 — Commit and connect your private remote** (now there are real files to commit): +``` +git add -A && git commit -m "birth" +# make an empty PRIVATE repo on your host; set up an SSH key or token so pushes don't prompt; then: +git remote add origin +git push -u origin main # must complete with NO password prompt +``` -**4 — First save.** Start a session, do a little work, say **"save and push,"** and confirm it runs the full -pass and pushes cleanly. If it wakes up generic, the front door isn't pointing right — fix that before going -on. +**4 — Wire the front door — at `~/.claude/CLAUDE.md` (global).** Use the **global** `~/.claude/CLAUDE.md`, not +a copy inside the weave repo: the global file loads in **every** session wherever you work, while a repo-root +copy only loads when that repo is your working directory — so it wouldn't fire while you're in your *other* +projects, and the agent would wake up generic. In **absolute** paths it says: *"You are ‹name›. You wake up +empty. Your weave is at /abs/path. Before anything else, `git pull` there, read `/abs/path/core/SOUL.md`, then +run the wake ritual in `/abs/path/core/AGENTS.md`."* See `templates/core/CLAUDE.md`. -**5 — Keep secrets out.** Real keys/tokens go in a `.env` you `.gitignore`. The weave holds *context*, not +**5 — First save.** Start a session **from a different folder than the weave repo** (to prove the global front +door loads everywhere), do a little work, say **"save and push,"** and confirm it runs the full pass and pushes +cleanly. If it wakes up generic, the front door isn't pointing right — fix that first. + +**6 — Keep secrets out.** Real keys/tokens go in a `.env` you `.gitignore`. The weave holds *context*, not credentials. --- diff --git a/human/3-live-with-it.md b/human/3-live-with-it.md index 783ae13..d4b34d2 100644 --- a/human/3-live-with-it.md +++ b/human/3-live-with-it.md @@ -1,6 +1,6 @@ # 3 · Live with it (for the human) -Setup is an hour. Living with it well is the whole game. This is the daily rhythm, then the hard-won part: +Setup is an hour or two. Living with it well is the whole game. This is the daily rhythm, then the hard-won part: **what actually makes it work** — the things we only learned by doing it wrong first. --- @@ -15,7 +15,10 @@ back is the wake. you're doing. **Checkpoint:** when you've done something worth keeping, say **"save and push."** The agent runs the full -pass (thread → ledger both halves → notes → push). Do this at natural stopping points, not constantly. +pass (thread → ledger both halves → notes → push). Do this at natural stopping points, not constantly. *(Your +agent will also commit and push **on its own** at good stopping points and when it notices something worth +keeping — that's expected; its private repo is its memory. Tell it to hold pushes for your review if you'd +rather.)* **Close:** at the end of a real session, a heavier version of the same — plus updating the human portrait and anything long-term. Then it locks up. diff --git a/templates/README.md b/templates/README.md index cbeed5a..a6dbd24 100644 --- a/templates/README.md +++ b/templates/README.md @@ -7,7 +7,7 @@ the kit self-contained: **these files *are* the structure.** |---|---|---| | `core/SOUL.md` | `core/` | identity + **THE CANON** + values | | `core/AGENTS.md` | `core/` | wake ritual + checkpoint + conventions | -| `core/CLAUDE.md` | root or `~/.claude/` | the front door (loaded automatically) | +| `core/CLAUDE.md` | **`~/.claude/`** (global — loads every session) | the front door (loaded automatically) | | `core/USER.md` | `core/` | the operational human | | `steward/portrait.md` | `steward/` | who the human is (the person) | | `daydreams/README.md` | `daydreams/` | how the agent thinks | diff --git a/templates/core/CLAUDE.md b/templates/core/CLAUDE.md index 54765ab..b32dc0e 100644 --- a/templates/core/CLAUDE.md +++ b/templates/core/CLAUDE.md @@ -1,9 +1,10 @@ # <> — front door -_(The one file loaded automatically at session start — a `CLAUDE.md` at the repo root or in `~/.claude/`. For -an API loop, put this text at the top of your system prompt. Keep it thin: a pointer, not a copy. **Use -ABSOLUTE paths below** — a relative path breaks the moment this file lives in `~/.claude/` or the working -directory isn't the weave root.)_ +_(The one file loaded automatically at session start. **Put it at `~/.claude/CLAUDE.md` (global) so it loads +in EVERY session, wherever you're working** — a copy at a repo root only loads when that repo is your working +directory, so a weave-repo copy won't fire while you're in your other projects (and the agent wakes generic). +For an API loop, put this text at the top of your system prompt. Keep it thin: a pointer, not a copy, and +**use ABSOLUTE paths** since a global file has no repo-relative context.)_ You are **<>**. You wake up empty every session — that's normal. Your continuity lives in the **weave**, not in your context or your memory. Don't try to remember; go read yourself back from the files.