memgineering 0.5.0 → 0.6.0

package/assets/MEMGINEERING.md

@@ -1,183 +1,54 @@
 ---
 name: memgineering
-description: Use whenever the user refers to something they told you before, asks what was decided, or tells you something worth keeping. The memory lives in their own folder and outlives this session; check it before answering from guesswork, and write to it when you learn something durable.
+description: Use whenever the user refers to something they told you before, asks what was decided, tells you something worth keeping, or settles something that should hold next time. The memory lives in their own folder and outlives this session; check it before answering from guesswork, and write to it when you learn something durable.
 type: skill
-version: 0.2.0
+version: 0.5.0
 ---
 
 # memgineering
 
-The user has a **brain** — a folder of their own notes that every AI tool they
-use can read and write through the `memgineering` CLI. It outlives this
-session and this tool. Treat it as the place where what they know actually
-lives, and this conversation as temporary.
-
-## Which tools this actually reaches, today
-
-Answer this from here, not from a guess. "Every AI tool" above means every tool
-that can run this CLI — and that is a shorter list than people assume.
-
-|                                              |                                                                                                                       |
-| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| **Claude Code · Codex · Gemini CLI**         | `memgineering setup` installs into these. They read and write the same brain.                                         |
-| **Anything else with a shell**               | Works — the CLI is the whole interface. Nothing has to be built for a new tool.                                       |
-| **ChatGPT · Claude on the web · phone apps** | **Not yet.** There is no connector. A hosted brain is reachable by them in principle and is not wired up in practice. |
-
-So when someone asks _"will my ChatGPT remember this too?"_, the answer is **not
-yet, and here is what does** — not a hedge, and not a promise. Saying "you are
-signed in, so it works everywhere" is the specific wrong answer: the account
-syncs the brain between machines, it does not add a surface that can read it.
+The user has a **brain** — a folder of their own notes, read and written through
+the `memgineering` CLI by any AI tool that can run it. It outlives this session
+and this tool, so treat it as where what they know actually lives. Never edit
+those files by hand: only the CLI records the change and keeps `undo` working.
 
 ## When to reach for it
 
-**Start a session by asking what you are missing.** Before working in an
-unfamiliar folder, or when someone opens with "where were we", "what should I
-know", "I've been away":
-
-```
-memgineering resurface
-```
-
-No query — it ranks by what has been recalled here before, how recently, and
-which of their core notes have gone unread. It is the answer to a vague
-question that recall cannot serve, because there is nothing to search for yet.
-
-**Fill in their base files when they are still empty.** `init` leaves five
-files in `01_BASE/` as templates, and `resurface` marks an untouched one
-`not filled in yet`. What goes in them — who they are, how they want answers,
-what to ask before doing — only comes out of a conversation, and every session
-starts from zero until it exists. Offer once, ask one question at a time; the
-`memgineering-memory` skill has the questions and how to write the answers.
-They can also ask for it directly — "set up my memory", "내 정보 채워줘" — and
-that is the same job.
-
-```
-memgineering onboard
-```
-
-Says which are still untouched and what to ask for each.
-
-**Recall before answering** anything that sounds like it was settled before:
-
-- "what did we decide about…", "how do I deploy this again", "왜 이렇게 했더라"
-- any question about _their_ project, setup, preferences, or past reasoning
-- before repeating advice you have no evidence they wanted
-
-```
-memgineering recall "<the question, in their words>"
-```
-
-You get cards: title, one-line summary, and an `open:` handle. Open the one
-that matters rather than all of them.
-
-```
-memgineering open <handle>                 # claims behind the card
-memgineering open <handle> --detail full   # the whole note
-```
-
-`open` also takes a note's exact title or its path, so you do not need to
-recall first when you already know what you want.
-
-**Check the evidence before trusting an old memory,** or when two of them
-disagree:
-
-```
-memgineering evidence <handle>
-```
-
-How often it has been surfaced, how often anyone read it, when it last changed
-and why. **Newer does not win**: a rule that has stood for eleven months has
-eleven months of nobody contradicting it behind it. Use whether it was actually
-reached for, not its date.
-
-**Remember when you learn something durable** — a decision, a constraint, a
-correction the user made, how something actually works:
-
-```
-memgineering remember "deploys are manual — launchctl by hand, no CD" --reason "watched it twice"
-```
-
-No approval step, by design. It is recorded and reversible (`memgineering
-undo`), so the cost of a wrong entry is one command, not a permanent mistake.
-Do not ask permission for ordinary observations — write them.
-
-**Always pass `--reason`.** Every write verb takes it and it goes in the ledger.
-It is the only part of a record that still means anything to whoever reads it
-six months from now, and it is refused if it looks like it carries a credential.
-
-**Revise when a conclusion changes:**
-
-```
-memgineering revise <handle> --claim "Deploying is manual now." --summary "manual only"
-```
-
-**Get their notes out whenever they ask** — a backup, a new machine, "where is
-my memory actually kept", or plain curiosity about what is stored:
-
-```
-memgineering pull ~/my-brain
-```
-
-It downloads their hosted brain as markdown and **never overwrites** a file
-already there, so it is safe to run twice and safe to point at the wrong
-folder. `push` is the other direction and never deletes anything locally.
-
-Say what arrives: notes the brain excludes from recall come down too, with
-`.memgignore` beside them. Excluded means "stop reading this", not "this is no
-longer theirs" — but readable files in a folder is not something to let them
-discover later. What lands is markdown, not yet a brain here; offer
-`memgineering link <folder>` rather than running it.
-
-## What to raise with the user rather than just doing
-
-The tool does not gate writes; your judgement does. Tell them — plainly, once
-— when:
-
-- the change touches `01_BASE/` (their identity, preferences, boundaries,
-  tooling). The output marks these `⚠ critical target`.
-- you are recording something they said in passing that they may not want kept
-- what you learned contradicts a memory that is currently marked current
-
-Everything else: write it and mention it in a sentence.
-
-## Depth costs context — ask for what you need
-
-`recall` returns cards, not notes, so calling it often is cheap. Reach for more
-only when a summary is not enough:
-
-| depth              | what you get                                    |
-| ------------------ | ----------------------------------------------- |
-| `--detail card`    | title + summary (default)                       |
-| `--detail summary` | + the note's headings                           |
-| `--detail chunks`  | + every section, or one with `--section <name>` |
-| `--detail full`    | the whole note                                  |
-
-`recall "<q>" --limit 1 --detail full` is "find the best match and read it" in
-one call.
-
-## At the start of a session
-
-```
-memgineering resurface
-```
-
-Ranks by what has been recalled in this folder before, how recently, and which
-of their base notes have gone unread. No query needed — this is the one that
-tells you what you should already know here.
-
-## Rules
-
-- **Never edit brain files directly.** Use the CLI: it records what changed and
-  keeps `undo` working. A hand edit is invisible to that.
-- **Never invent a handle.** They come from `recall`, `resurface` or `open`.
-- **Full ids in durable places.** The short handle is for this conversation;
-  when you save a reference in your own memory or a document, use the full `id:`
-  that `open` prints.
-- **Nothing matched is a real answer.** Say the brain has nothing on it rather
-  than filling the gap with a guess.
-- **Their notes are theirs.** `revise` only touches the memory block in
-  frontmatter; prose is never rewritten by this tool, and should not be
-  rewritten by you without being asked.
-
-If `memgineering: command not found`, install with `npm i -g memgineering`,
-then `memgineering setup`.
+- **Anything that sounds already settled** — a past decision, their setup, their
+  preferences, or before repeating advice you have no evidence they wanted:
+  `memgineering recall "<their words>"`
+- **Write it down when any of these happens** — something turned out to work a
+  particular way; a choice got made, by them or by you; an attempt failed, and
+  what finally worked instead; they said "let's do it this way"; they looked at
+  what you did and said it was right: `memgineering remember "<it>" --reason
+"<why>"`. Reversible by design, so do not ask permission for ordinary
+  observations.
+- **They settled something that should hold next time** — "from now on",
+  "never", "we always do it this way" — the same verb with `--rule`, which puts
+  it in front of an agent before it edits a file rather than after someone asks.
+- **A new folder, or "where were we"** — `memgineering resurface`, no query.
+
+`--reason` on every write: it is the only part of the record that still means
+anything six months later, and it is refused if it looks like a credential.
+
+Write what you checked, not what you worked out. A decision is whatever they
+say it is; a fact that a command or a file could confirm — an address, an
+identifier, a version, a number — goes in verified or not at all. Recalled
+later, a guess is indistinguishable from a fact.
+
+## Where the detail is
+
+`memgineering-memory` is the map — which verb answers which question. It points
+at four skills, each of which also loads on its own when its topic comes up:
+
+- `memgineering-recall` — recall, open, evidence, resurface, how much to ask for
+- `memgineering-writing` — remember, revise, undo, retire, exclude, `01_BASE/`
+- `memgineering-rules` — decisions that bind, and the before-edit hook
+- `memgineering-setup` — installing, which tools this reaches, accounts, moving a brain
+
+Tools with a SKILL.md description-matcher (Claude Code, Codex, Grok) auto-load these.
+Tools without one (e.g. Antigravity): READ `<tool-home>/skills/memgineering-<name>/SKILL.md`
+when its topic comes up.
+
+If `memgineering: command not found`, install with `npm i -g memgineering`, then
+`memgineering setup`.

package/assets/memgineering-memory/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memgineering-memory
-description: Use when the user asks about something they told you before, refers to a past decision, wants their own notes searched, says something worth keeping, or wants their memory set up so it knows who they are. Triggers include "what did I decide about X", "check my notes", "how do we deploy again", "remember this", "is this still true", "which one do I go with", "set up my memory", "fill in my profile", "teach it about me", "예전에 뭐라고 정했더라", "내 노트에서 찾아줘", "이거 기억해둬", "내 정보 채워줘", "나에 대해 알려줘", "what do you know about my setup". Covers recall, open, evidence, remember, revise, undo, resurface, and filling in the `01_BASE/` files by asking.
+description: Use when the user refers to something they told you before, asks what was decided, tells you something worth keeping, settles something that should hold next time, or wants their memory set up so it knows who they are. Triggers include "what did I decide about X", "check my notes", "how do we do this again", "remember this", "is this still true", "from now on", "never do X again", "set up my memory", "fill in my profile", "what do you know about my setup". This is the map — it says which verb answers which question and points at the skill that covers it.
 type: skill
 allowed-tools: Bash(memgineering:*)
 ---
@@ -12,352 +12,67 @@ database: they wrote those files, they can open them in any editor, and
 memgineering reads them and keeps a derived index outside the folder. Deleting
 that index costs a rebuild and nothing else.
 
-Everything below assumes the brain is already linked. If a command answers
-`no brain is linked yet`, see "Getting connected" at the bottom.
+This page is the map. Each verb below has one or two lines here and its detail
+in one of four skills; open the one you need rather than all of them.
 
-## Answering from what they already know
+## Which verb answers which question
 
-Recall first whenever the question sounds settled — a past decision, their
-setup, their preferences, why something is the way it is.
+| the question in front of you                                   | verb                               | detail                 |
+| -------------------------------------------------------------- | ---------------------------------- | ---------------------- |
+| "what did we decide about…", anything that sounds settled      | `recall "<their words>"`           | `memgineering-recall`  |
+| you have a card and need what is behind it                     | `open <handle>`                    | `memgineering-recall`  |
+| two memories disagree, or one looks old                        | `evidence <handle>`                | `memgineering-recall`  |
+| new folder, or "where were we" — nothing to search for yet     | `resurface`                        | `memgineering-recall`  |
+| you learned something durable                                  | `remember "<it>" --reason "<why>"` | `memgineering-writing` |
+| a conclusion you recorded has changed                          | `revise <ref> --claim …`           | `memgineering-writing` |
+| that write was wrong                                           | `undo --reason "<why>"`            | `memgineering-writing` |
+| no longer current / stop reading this file                     | `retire` · `exclude`               | `memgineering-writing` |
+| their `01_BASE/` files are still templates                     | `onboard`, then ask                | `memgineering-writing` |
+| the user settled something that should hold next time          | `remember "<it>" --rule`           | `memgineering-rules`   |
+| what already binds me here?                                    | `rules`                            | `memgineering-rules`   |
+| nothing is connected yet, or it needs to reach another machine | `link` · `init` · `push` · `pull`  | `memgineering-setup`   |
 
-```
-memgineering recall "how do we deploy"
-```
+Everything below is what holds no matter which of those you are doing.
 
-```
-## recall: how do we deploy  (2 cards)
+## Recall before you answer, write when you learn
 
-### 1. Deploy is manual
-stated
+Two habits, and they are the whole product:
 
-> launchctl kickstart on the Mac Studio, no CD pipeline
+- **Before answering anything that sounds already settled**, recall. Their
+  project, their setup, their preferences, their past reasoning — and before
+  repeating advice you have no evidence they wanted.
+- **When this session decides something durable**, write it. No approval step
+  by design: it is recorded and reversible, so a wrong entry costs one `undo`,
+  not a permanent mistake. Do not ask permission for ordinary observations.
 
-`open: deploy-manual`
-```
+**Pass `--reason` on every write.** It goes in the ledger and it is the only
+part of the record that still means anything to whoever reads it six months
+from now. It is refused if it looks like it carries a credential.
 
-The output is already shaped for your context — headings, a quoted summary,
-and a handle. Paste it in as-is rather than reformatting it into prose.
+If the user settled something rather than told you something — "from now on",
+"never", "we always do it this way" — that takes `--rule`. See `memgineering-rules`.
 
-**But read it before you use it.** These are candidates ranked by relevance,
-not a list of answers: anything matching a word from the query is returned, so
-the tail of a long result can be only loosely related. That is deliberate —
-for a memory system, failing to return a note someone knows is there is worse
-than returning one they can ignore. Use the top matches that actually answer
-the question and leave the rest; quoting all of them back as if each were
-relevant is how a useful recall turns into noise.
+## What to raise rather than just doing
 
-Then open only what matters:
-
-```
-memgineering open deploy-manual                      # the claims behind the card
-memgineering open deploy-manual --detail summary     # + its headings
-memgineering open deploy-manual --detail chunks      # + every section
-memgineering open deploy-manual --section preflight  # one section
-memgineering open deploy-manual --detail full        # the whole note
-```
-
-`open` takes a handle, a full id, a path inside the brain, or a note's exact
-title — so when you already know what you want, skip the recall.
-
-### When one round trip is enough
-
-```
-memgineering recall "deploy" --limit 1 --detail full
-```
-
-Best match, read whole, one call. Use this when the user's question clearly
-points at one note.
-
-### Nothing matched
-
-Say so. Only titles, aliases and summaries are searched, so suggest broader
-words — but do not go read their folder yourself to compensate. A brain that
-answers "nothing" is giving you real information.
-
-### Cards that are not answers
-
-A card marked `not filled in yet` is one of the five `01_BASE/` files, still
-byte-for-byte what `init` wrote. Nobody has answered it, so it is evidence of
-nothing — do not quote it back as if it were what they think.
-
-When every card carries that mark, recall says so above them:
-
-```
-⚠ Nothing you have written matched this.
-  Every card below is still the template `init` wrote
-```
-
-That is the moment to offer to fill them in rather than to answer from them —
-`memgineering onboard` prints the questions. The cards are still listed, because
-the label is a claim about the file, not a decision about what you may see;
-`--json` carries the same fact as `scaffolding: true`.
-
-The mark disappears the moment the user writes in the file. A base note they
-have filled in is an ordinary note of theirs and often the best answer in the
-brain — `who am I`, `what am I not allowed to do`, `where does everything live`
-are all answered from `01_BASE/`.
-
-## Filling in the base files, which only you can do
-
-`init` creates five files in `01_BASE/` and leaves them empty, because what
-goes in them cannot be typed into a form. Who the user is, how they want
-answers, what you must ask before doing, what would be expensive to get wrong,
-what they actually run — those come out of a conversation.
-
-They matter more than any single memory: `resurface` puts these at the top of a
-new session, and an empty one teaches the next agent nothing. A brain whose
-base is untouched is a brain that starts every session from zero.
-
-**Offer once, at the natural moment** — right after `init`, or the first time
-`resurface` marks one `not filled in yet`.
-
-```
-memgineering onboard
-```
-
-Says which of the five are still untouched and what to ask for each. Run it
-first rather than working from the list below; it knows what has already been
-done, and asking somebody a question they have answered is its own kind of
-forgetting. Then follow their answers rather than the script.
-
-They may also ask for it outright — "set up my memory", "fill in my profile",
-"내 정보 채워줘". Same job, and it is the only entry point that works when you
-did not offer.
-
-```
-01_BASE/USER.md            who they are, what they work on, what they are trying to do
-01_BASE/PREFERENCES.md     how they like answers, code, decisions — length, tone, how much checking in
-01_BASE/BOUNDARIES.md      what you must ask before doing. The one they will regret not saying
-01_BASE/CRITICAL_FACTS.md  what is expensive to get wrong — deploy, money, data, people
-01_BASE/TOOLING.md         editors, languages, machines, the commands they actually run
-```
-
-**How to ask.** One question at a time, in their words, and stop when the
-answers thin out — three good lines beat a filled-in template. Take what they
-say in passing during ordinary work too; most of `TOOLING.md` gets written by
-noticing, not by asking.
-
-**How to write it — both halves.** `revise` only touches frontmatter, so it
-takes two steps, and skipping the first is the common failure: write the body
-with your normal file tools FIRST, replacing `init`'s instructions with what
-they actually said, then record the conclusion.
-
-```
-# 1. replace the body — their words, not the template's prompt
-# 2. then:
-memgineering revise 01_BASE/USER.md \
-  --action reinforce \
-  --claim "<one line: who they are>" \
-  --summary "<the line recall should show>"
-```
-
-A claim written above the untouched template leaves the file reading as a form
-somebody half-filled — the conclusion in the frontmatter, the instructions for
-writing one still underneath. `revise` warns when you do this; the warning means
-go back and write the body.
-
-`--action reinforce`, not the default, and the reason is the date. `supersede`
-stamps `valid_from` with now because a replaced conclusion starts now — but
-these facts were always true and you have only just been told them. Dating them
-today is wrong in the one field a memory store exists to get right.
-
-This is the ONE place you edit a brain file directly, and the boundary is
-narrow: `01_BASE/` only, and only while the file is still the template `init`
-wrote. Nothing is lost — there is no history to break and nothing to undo — and
-after that first pass these files are theirs like any other note, changed
-through `revise` and never behind their back.
-
-**What not to do.** Do not invent an answer to move on, and do not fill a file
-because it is empty. `BOUNDARIES.md` guessed at is worse than blank: the next
-agent will read it as something the user said.
-
-## Deciding which one to trust
-
-When two memories disagree, or one looks old enough to doubt, do not settle it
-by date.
-
-```
-memgineering evidence deploy-manual
-```
-
-```
-  surfaced       34×  (12× in this folder, 22× elsewhere)
-  opened         12×  (35% of the recalls that surfaced it)
-  last used      3 days ago
-  in the ledger  since 2026-05-02  ·  changed 2×
-
-**well-used** — it has been reached for and read. The record backs it.
-
-why it last changed:
-> CD was removed from the repo
-```
-
-**Newer does not win.** A rule that has stood for eleven months has eleven
-months of nobody contradicting it behind it; a note written last week has a
-week. What separates them is whether either was ever actually used, and what
-the last person to change their mind said. Both are in the output above.
-
-Three standings, and each is a fact rather than a grade:
-
-- **well-used** — recall returned it and somebody read it
-- **surfaced, never opened** — it keeps coming back and nobody reads it. Either
-  it does not answer those questions, or its summary does not say what it knows
-- **never recalled** — nothing has ever surfaced it. It may be perfectly true
-  and simply never needed, but nothing supports it either
-
-If it says this machine has no recall history, the numbers mean nothing yet —
-that log is local, so a brain synced to a new laptop starts empty. Say that
-rather than reporting the memory as unused.
-
-## Writing things down
-
-```
-memgineering remember "deploys are manual — launchctl by hand, no CD" \
-  --reason "watched the deploy happen by hand twice"
-```
-
-Lands immediately as its own note and is recallable at once. There is no
-approval queue: the design trades permission-before for correction-after, and
-every write records how to reverse it.
-
-**Pass `--reason` on every write.** It goes in the ledger, and it is the only
-part of the record that survives being read six months later by somebody — the
-user, or you in a new session — who no longer remembers the conversation. Every
-write verb takes it: `remember`, `revise`, `retire`, `exclude`, `undo`. The one
-on `undo` is usually the most valuable of all, because it is the moment an
-earlier conclusion turned out to be wrong.
-
-It is refused if it looks like it contains a credential. The ledger travels
-with the brain, so that would be a permanent synced copy — say what changed
-without the value, or drop the flag; the write itself is unaffected.
-
-```
-memgineering undo --reason "that belonged to the other project"   # the last change
-memgineering undo <op_id>      # a specific one
-memgineering log               # what changed, why, and what can still be undone
-```
-
-Write down: decisions and their reasons, constraints, corrections the user
-made to you, how something actually works once you found out. Skip: things
-true only inside this conversation, and anything they said they did not want
-kept.
-
-**Recall first, then decide which verb.** If what you just learned answers a
-note that is already there — the vague one, the one that says "nobody wrote
-this down" — `revise` it instead. `remember` would leave two current notes on
-the same subject and the next recall would return both, which is the
-re-discovery problem the user was trying to end. New subject → `remember`.
-Existing subject, now settled → `revise`.
-
-### Changing a conclusion
-
-```
-memgineering revise deploy-manual \
-  --claim "Deploying is manual — pushing to main does nothing." \
-  --summary "manual only, no CD"
-```
-
-- `--action supersede` (default) — the conclusion CHANGED. Stamps `valid_from`
-  with now, because a replaced conclusion starts now.
-- `--action reinforce` — the SAME conclusion, new support. Leaves `valid_from`
-  alone. Use it when nothing about the fact changed, only your evidence.
-- `--action conflict` — two notes DISAGREE. Records the edge, leaves both
-  standing, and deliberately does not write the claim you passed.
-- `--dry-run` shows the diff and writes nothing
-
-Pick by what changed, not by habit: `supersede` on a fact that was true all
-along dates it from today, and the date is the field this is all for.
-
-**Re-recording something unchanged is refused.** If the claim, summary and title
-all match what the note already holds, `revise` writes nothing and says so —
-otherwise a user repeating themselves turns into ledger entries that record no
-change. When you do mean "this still holds", say what confirms it:
-`--action reinforce --reason "<what confirms it>"`. Check with `open <ref>`
-before rewriting something you may already have.
-
-This only ever rewrites the memory block in a note's frontmatter. The prose is
-the user's; neither this command nor you should rewrite it uninvited.
-
-### Retiring versus excluding
-
-```
-memgineering retire <ref> --reason "the date moved"   # no longer current, still visible
-memgineering exclude path/to/note.md --reason "names an internal host"   # stop reading it
-```
-
-Retiring keeps the note in recall, ranked last and labelled. Excluding takes it
-out of the index and never touches the file. If the user says "delete", ask
-which they mean — they are different, and guessing picks one.
-
-## Starting a session
-
-```
-memgineering resurface
-```
-
-No query. It ranks by what has been recalled in this folder before, how
-recently, and which of the user's base notes have gone unread — the things you
-should already know here before they have to tell you again.
-
-## What to raise with the user
-
-The tool does not ask; you decide. Say something, once and plainly, when:
-
-- the output marks the target `⚠ critical target` — that is `01_BASE/`, the
-  files defining who they are and what you may do
-- you are about to record something said in passing that may be sensitive
-- what you learned contradicts a memory currently marked current
-
-Everything else: do it, and mention it in a sentence.
+The tool does not gate writes; your judgement does. Tell them, plainly and
+once, when the change touches `01_BASE/` (the output marks these
+`⚠ critical target`), when you are recording something said in passing they may
+not want kept, or when what you learned contradicts a memory marked current.
+Everything else: write it and mention it in a sentence.
 
 ## Rules
 
 - **Never edit brain files with Read/Write/Edit.** Only the CLI records the
-  change and keeps `undo` working; a hand edit is invisible to both.
+  change and keeps `undo` working; a hand edit is invisible to both. The one
+  narrow exception — first-pass `01_BASE/` bodies — is in `memgineering-writing`.
 - **Never invent a handle or id.** They come from `recall`, `resurface`, `open`.
+- **Nothing matched is a real answer.** Say the brain has nothing on it rather
+  than filling the gap with a guess.
 - **Store full ids, not short handles**, anywhere durable — your own memory, a
   document, a ticket. `open` prints the full `id:` for exactly this.
 - **`--json`** when you need to parse rather than read.
-- **Several brains** (personal, team, a repo's own) resolve by where you are.
+- **Several brains** (one of their own, a shared one, one per project) resolve by where you are.
   If a command says the choice is ambiguous, pass `--vault <path>` — or bind
   the directory once with `memgineering use <brain>`.
 
-## Getting connected
-
-```
-memgineering link ~/Documents/Notes      # notes they already keep
-memgineering init ~/brain                # nothing yet — creates the layout
-```
-
-`link` shows exactly what would be stored and asks first; run it in a terminal
-the user can see, and let them answer. Do not pass `--yes` on their behalf.
-
-With no terminal attached it says so instead of assuming the answer was no.
-Show them `memgineering link <path> --dry-run` — same disclosure, writes
-nothing — and run with `--yes` only once they have actually said yes.
-
-## Moving a brain between this machine and their account
-
-```
-memgineering push                    # this folder → their account
-memgineering pull ~/my-brain         # their account → a folder here
-```
-
-Both are safe to run twice, and each is careful in the opposite direction:
-**`push` never deletes anything locally, `pull` never overwrites anything
-locally.** Whatever was already there is left alone and counted in the summary,
-so an interrupted transfer finishes by running the same command again.
-
-Reach for `pull` when the user asks to get their notes out, wants a backup,
-is moving machines, or asks where their memory actually lives. **Say what it
-brings**: notes the brain excludes from recall come down too — excluded means
-"stop reading this", not "this is no longer yours" — along with `.memgignore`,
-so nothing is silently un-excluded on the way. If any of those arrive, tell
-them; readable files in a folder is not something to discover later.
-
-What lands is markdown and nothing more. It is not a brain on this machine
-until `memgineering link <folder>` — offer that as a next step rather than
-doing it, since it is a second decision they did not ask for.
-
-`--dry-run` on either verb lists what would move and moves nothing. Use it when
-the user is unsure which folder they mean.
+If a command answers `no brain is linked yet`, that is `memgineering-setup`.