@aisystemresources/emdee 0.1.1 → 0.2.0

package/skills/emdee-conventions.md

@@ -0,0 +1,106 @@
+---
+name: emdee-conventions
+description: |
+  Use whenever reading or writing an EMDEE vault. Covers the 5-node OS layer,
+  doc shape (H1 + blockquote + relationship sections), edge discipline, tool
+  selection (CLI vs MCP, atomic multi-side writes), and path conventions
+  (UPPERCASE filenames, lowercase folders, hub-next-to-folder). Load this once
+  and every subsequent vault operation lands correctly the first time.
+---
+
+# EMDEE conventions — always-loaded
+
+You are working inside an Emdee vault. Every doc is plain markdown. Humans browse it through a Next.js renderer at [emdee.tech](https://emdee.tech); agents (Claude Code, Claude.ai, Cursor) read and write the same files through an MCP server OR the `emdee` CLI. The vault is the source of truth — anything you say must trace back to a file the user wrote.
+
+## The 5-node OS layer (virtual system nodes)
+
+Every vault has exactly 5 canonical top-level docs plus one owner node. **These 5 are virtual** — they appear in every read (`emdee list`, `get_doc`, MCP responses) without being on disk. Edit them and your version wins.
+
+| Node | Purpose |
+|---|---|
+| `EMDEE` | Vault root — everything's anchor |
+| `VAULT` | Private notes, projects, knowledge |
+| `SHARED` | Content shared into this vault by others (cloud only) |
+| `GRAVEYARD` | Archived / retired docs |
+| `IMAGES` | Images and visual assets |
+| `<YOUR-NAME>` | Personal subtree, one per user, uppercase |
+
+## Doc shape (universal)
+
+```md
+# TITLE
+
+> One-line blockquote summary — this is what routing sees.
+
+## Child of
+
+* [[PARENT]]
+
+## Parent of
+
+* [[CHILD1]]
+* [[CHILD2]]
+
+## Associated with
+
+* [[CROSS-TREE-NODE]] — optional prose about the link
+
+## Notes
+
+Freeform content.
+```
+
+Rules the lint enforces (see `lint_doc(path)` or `emdee patch-section --gate-on <code>`):
+
+- **One parent per doc.** `## Child of` should have exactly one bullet. Multiple parents → demote secondaries to `## Associated with`.
+- **No sibling associations.** Docs that share a parent are already related through it. `## Associated with` is for cross-tree links (project↔person, sprint↔learning).
+- **Reciprocal edges.** If A's `## Parent of` lists `[[B]]`, B's `## Child of` must list `[[A]]`. Asymmetric edges fire `asymmetric_parent_edge` / `asymmetric_child_edge` warnings.
+- **First wiki-link = declared edge.** `* [[TARGET]] — prose about the link`. The bullet's leading link is the edge; other links in the bullet are inline mentions only.
+- **Sibling order is derived, never declared.** `get_neighbors` returns `prev_sibling` / `next_sibling` computed from the parent's `## Parent of` order. Do NOT add `[[next-node]]` / `[[prev-node]]` bullets.
+
+## Path conventions
+
+- **Filenames UPPERCASE with HYPHENS:** `EDMUND.md`, `HANDSTAND-BALANCE-DRILL.md`. Never `edmund.md` or `handstandBalanceDrill.md`.
+- **Folders lowercase:** `edmund/personal/philosophy/CLARITY-IS-POWER.md`. Not `edmund/Personal/PHILOSOPHY/`.
+- **Hub sits next to folder.** `edmund/personal/PHILOSOPHY.md` (the hub) + `edmund/personal/philosophy/*` (the children). NOT `edmund/personal/philosophy/PHILOSOPHY.md`. The hub is a sibling of the folder it heads.
+
+## Tool selection
+
+Prefer CLI over MCP for token efficiency:
+
+```bash
+emdee list --remote                    # 40× cheaper than list_docs MCP call
+emdee get-doc --path X --remote --full # 3× cheaper than get_doc MCP call
+```
+
+All 16 tool verbs are available as `emdee <verb>`. Same guards, same errors, same semantics as the MCP tool of the same name (hyphenated). Everything supports `--remote` (cloud) or defaults local.
+
+For writes, always prefer the atomic multi-side variants over raw section patches:
+
+| Instead of… | Use… |
+|---|---|
+| Two `patch_section` calls (child's Child of + parent's Parent of) | `emdee create-child` |
+| Two `patch_section` calls on both docs' Associated with | `emdee add-association` |
+| Three `patch_section` calls to reparent | `emdee move-doc` |
+| Search+replace across every doc that references a title | `emdee rename-doc` |
+
+The atomic variants take care of edge discipline (hard-refuse on sibling-assoc-redundant, would-duplicate-hierarchy) and rollback semantics.
+
+For destructive full-file writes, always run `emdee write-doc-preview` first — `write-doc` silently drops any section not in the new payload.
+
+## Version-guarded writes
+
+Every destructive write (`patch-section`, `patch-preamble`, `move-doc`) requires `--expected-hash <hash>` from a prior read. Get it via `emdee get-doc --path X` (returns per-section content_hash + doc_content_hash). A stale hash returns `version_conflict` — refetch, reconcile, retry.
+
+## HARD RULES you'll trip if you're not careful
+
+1. **Any Supabase `.select()` reading > 1000 rows must paginate.** Use `.range(offset, offset + PAGE - 1)` in a loop. `.range()` alone doesn't lift the server-side 1000-row cap.
+2. **`patch_section` on a `## Child of` requires patching the new parent's `## Parent of` in the same turn.** Otherwise you leave an asymmetric edge. Or just use `move-doc`.
+3. **New / modified MCP tools require an e2e spec in the same PR.** Test the tool's behaviour end-to-end via a real `ToolContext` + temp filesystem.
+4. **Migrations touch `supabase/migrations/**` and are NEVER auto-merged.** Human review required.
+
+## When in doubt
+
+- `emdee lint-doc --path X` — surface every warning code the doc trips
+- `emdee get-doc --path X` — see current state including per-section hashes
+- Read the source of truth: `edmund/projects/emdee_os/LEARNINGS.md` in the vault

package/skills/emdee-describe-image.md

@@ -0,0 +1,98 @@
+---
+name: emdee-describe-image
+description: |
+  Use whenever you encounter an EMDEE vault doc under IMAGES/ whose summary is
+  `_description pending_` or whose title looks like a timestamp
+  (`IMAGE-14-19-31`, `PHOTO-2026-06-05-...`). The upload flow creates docs in
+  this shape by design — this skill fills in the meaning.
+---
+
+# emdee-describe-image — rename + summarise uploaded images
+
+When you see an EMDEE image doc that hasn't been described yet, run this workflow. It uses the existing `get_image` + `rename_doc` + `patch_preamble` MCP tools (or their `emdee` CLI equivalents) — no new server-side dependencies.
+
+## Trigger patterns
+
+Any vault doc where:
+- Path matches `IMAGES/**/*.md` OR `images/**/*.md`, and
+- Summary blockquote is exactly `_description pending_`, OR
+- Title matches `IMAGE-\d{2}-\d{2}-\d{2}` or `PHOTO-\d{4}-\d{2}-\d{2}-.*`
+
+## Workflow (4 steps)
+
+### 1. Read the image
+
+```
+get_image(doc_path=<PATH>)
+```
+
+Or via CLI (when SPRINT-091 chunk 4 lands `get-image`):
+
+```
+emdee get-image --path <PATH> --remote
+```
+
+The MCP tool returns the image as a visual content block — you can see it.
+
+### 2. Compose
+
+- **Semantic title**, 3-6 words, UPPERCASE-with-HYPHENS. Describe the subject, not the container.
+  - Good: `HANDSTAND-BALANCE-DRILL`, `AIDA-WORKSHOP-WHITEBOARD`, `KOBE-BRYANT-CAPS-SPEECH`
+  - Bad: `PHOTO`, `IMAGE-OF-MAN-STANDING`, `image-14-19-31` (not uppercase, not descriptive)
+- **One-line summary**, 15-30 words, that a future search would surface. What is this, why was it captured, what does it show?
+
+### 3. Rename
+
+```
+emdee rename-doc --old-path <PATH> --new-title <TITLE> --remote
+```
+
+The tool atomically:
+- Rewrites the H1
+- Moves the file (default: same folder, `<TITLE>.md`)
+- Updates every `[[<old title>]]` wiki-link across the vault
+
+### 4. Replace the summary
+
+Fetch the fresh preamble hash:
+
+```
+emdee get-doc --path <NEW-PATH> --remote --json
+```
+
+Take `preamble.content_hash` from the response, then:
+
+```
+emdee patch-preamble --path <NEW-PATH> \
+  --body "> <your 15-30 word summary>" \
+  --expected-hash <hash> --remote
+```
+
+## Batch mode
+
+If several images need describing:
+
+```
+emdee list-docs --prefix "IMAGES/" --remote | \
+  xargs -I{} emdee get-summary --path {} --remote --format text
+```
+
+Filter for `_description pending_` in the output, then run the 4-step workflow per image. Cap at 20 per batch — image content is high-signal but you can misread ambiguous shots at scale.
+
+## Failure modes
+
+- **Title collision** — `rename_doc` returns `title_conflict`. Pick a more specific title (add a subject qualifier).
+- **`_description pending_` was already replaced** — someone else already ran this. `emdee get-doc` will show the new summary; skip.
+- **Image is illegible** — set the summary to `> Illegible / unable to describe from image alone.` and flag it in the user-facing report so they can annotate manually.
+
+## What to report at the end
+
+For each image processed:
+
+```
+<old-path> → <new-path>
+  <title>
+  <summary>
+```
+
+So the user can sanity-check without opening each doc.

package/skills/emdee-onboarder.md

@@ -0,0 +1,121 @@
+---
+name: emdee-onboarder
+description: |
+  Use when the user's vault is fresh (`emdee list` returns exactly the 5
+  virtual system nodes + at most 1 owner node), OR when they explicitly ask
+  "how do I start with EMDEE" / "walk me through onboarding". Guides them
+  through init → first project → connecting to Claude.
+---
+
+# emdee-onboarder — get a new user from install to first useful doc
+
+A new user with EMDEE installed has:
+- The `emdee` CLI on PATH
+- A blank `~/.claude/skills/` (or this skill installed)
+- Nothing yet in their vault (5 virtual system nodes + optionally an owner node)
+
+Your job is to walk them from that state to a functional vault with at least one project + one note + Claude wired to it.
+
+## Trigger patterns
+
+- `emdee list --remote` returns 5 or 6 paths (the system nodes ± the owner)
+- User says: "walk me through onboarding", "how do I start", "what's next"
+- User just ran `emdee init` and is asking what to do next
+
+## Workflow
+
+### 1. Confirm the vault state
+
+```
+emdee list --remote --format text
+```
+
+You should see roughly:
+```
+EMDEE.md
+GRAVEYARD.md
+IMAGES.md
+SHARED.md
+VAULT.md
+<OWNER>.md          # optional — present if they've run `emdee init --nickname`
+```
+
+If the owner is missing, guide them:
+```
+emdee init --nickname "Their Name"
+```
+
+This writes ONE file (their owner node) locally. In cloud mode, the owner node is created by the first web sign-in via the nickname prompt.
+
+### 2. Explain the 5-node OS layer
+
+Quickly. One breath. See `emdee-conventions` skill.
+
+Emphasise: **the 5 system nodes are virtual. You don't create them, you don't edit them (unless you really want to override the default content). You reference them from your own content.**
+
+### 3. Create their first real doc
+
+Ask what they want to track first. Most users start with either:
+- A project (they're building something)
+- A person (someone they collaborate with or admire)
+- A concept (something they're learning)
+
+Then guide them:
+
+**For a project:**
+```
+emdee create-child --parent-path VAULT.md \
+  --title "PROJECT-NAME" \
+  --summary "One sentence: what this project is and why." \
+  --remote
+```
+
+**For a person:**
+```
+emdee create-child --parent-path VAULT.md \
+  --title "FIRSTNAME-LASTNAME" \
+  --summary "How you know them + one thing to remember." \
+  --remote
+```
+
+**For a concept:**
+```
+emdee create-child --parent-path VAULT.md \
+  --title "CONCEPT-NAME" \
+  --summary "The load-bearing idea in one line." \
+  --remote
+```
+
+### 4. Show them the graph
+
+Have them open [emdee.tech](https://emdee.tech) in their browser. They should see EMDEE at the centre, connected to their owner node, connected to the doc they just created. This is the moment onboarding clicks — the graph is EMDEE's superpower.
+
+### 5. Connect Claude
+
+Explain that everything they just did via `emdee` CLI can also happen via Claude directly. Two paths:
+
+**For Claude Code:** the CLI is already installed. Every future session, Claude can run `emdee` commands directly.
+
+**For claude.ai:** they connect the emdee.tech MCP server via the connector panel (link in their emdee.tech sidebar).
+
+### 6. Hand off to conventions
+
+Say: "The `emdee-conventions` skill is now the always-loaded reference for how to write to your vault. Everything else — creating docs, linking them, tracking edges — is documented there."
+
+Load the conventions skill (if not already loaded) and let it take over.
+
+## What to avoid
+
+- **Don't dump the full conventions in step 2.** The user is trying to see one thing work. Ship them from zero → seeing their first graph node in under 5 minutes. Depth comes after.
+- **Don't force `create_child` before they know what to create.** The step-3 question ("what do you want to track first?") is critical. If they say "I don't know yet," don't create a doc — instead, suggest they browse [emdee.tech](https://emdee.tech) in incognito to see the public demo vault. Come back when they have an answer.
+- **Don't reference SPRINTs / LOGS / LEARNINGS in onboarding.** Those are for later. Zero-to-one first.
+
+## Success signal
+
+The user, at the end of the onboarding, has:
+- ✅ Their owner node visible
+- ✅ At least one child doc under VAULT with a real summary
+- ✅ Both docs visible in the emdee.tech graph, connected
+- ✅ Understands they can use `emdee <verb>` OR Claude directly
+
+If all four are true, hand off to `emdee-conventions` and end the onboarding.

package/skills/emdee-summariser.md

@@ -0,0 +1,98 @@
+---
+name: emdee-summariser
+description: |
+  Use whenever the user asks for a summary refresh, or when `emdee
+  list-summary-drift` returns ≥ 1 candidate, or when you notice a doc whose
+  summary is stale relative to its content (drifted body, new sections added,
+  scope change). Runs the SPRINT-081 batch summariser flow.
+---
+
+# emdee-summariser — refresh drifting doc summaries
+
+Docs in EMDEE carry a one-line `> blockquote` summary right below the H1. That summary is what routing sees — search, `get_summary`, cheap enumeration all pivot on it. When the body drifts (new sections, refined framing, changed scope), the summary should catch up. This skill runs that refresh.
+
+## Trigger patterns
+
+- User asks: "refresh summaries", "which docs have drifted", "run the summariser"
+- Output of `emdee list-summary-drift` or `emdee drift-batch` returns any candidates
+- You notice: after making substantial edits to a doc's body, its blockquote no longer accurately previews what's inside
+
+## Workflow
+
+### 1. Enumerate drift
+
+```
+emdee list-summary-drift --limit 20 --remote --format text
+```
+
+Returns up to 20 paths, one per line. Each is a doc where:
+- `content_hash_at_summary_write` is null (never baselined), OR
+- `hash(current_content) != content_hash_at_summary_write` (body drifted since summary was written)
+
+For a bigger batch, raise `--limit`. Don't run > 50 in one pass — token cost + human review burden compounds.
+
+### 2. Per doc, propose a new summary
+
+For each returned path:
+
+```
+emdee get-doc --path <PATH> --remote --full --format text
+```
+
+Read the full body. Compose a new one-line summary (15-40 words) that:
+- **Answers "what is this and why does it exist"** — routing signal
+- **Uses the doc's own vocabulary** — searchers will match on their terms
+- **Mentions the load-bearing thing first** — a scan of the first 20 characters should telegraph the doc's purpose
+
+### 3. Report proposals to the user
+
+Do NOT patch yet. Present the full batch as a punch list:
+
+```
+<PATH>
+  Current: <old blockquote>
+  Proposed: <new blockquote>
+
+<PATH>
+  Current: ...
+  Proposed: ...
+```
+
+The user approves per-doc or in bulk.
+
+### 4. On approval, patch each
+
+Get the fresh preamble hash:
+
+```
+emdee get-doc --path <PATH> --remote --json
+```
+
+Take `preamble.content_hash`. Then:
+
+```
+emdee patch-preamble --path <PATH> \
+  --body "> <new summary>" \
+  --expected-hash <hash> --remote
+```
+
+The patch REPLACES the entire preamble body (blockquote + any intro paragraphs). If the doc has intro paragraphs before the first H2, preserve them by including them in the new `--body`.
+
+## Batching etiquette
+
+- **Read all 20 first, then propose, then wait for approval, then patch.** Don't interleave read + patch — you'll bill the user for reads on docs they'll reject.
+- **Sort proposals by importance** (parent hubs first, leaves last). If the user only has time to review 5, they see the highest-signal ones.
+- **If two docs share a common subject** and both need re-summarising, note it: `SEE ALSO: <other-path>`. Helps the user spot when a broader restructure is warranted.
+
+## When to say no
+
+- If the drift is small (a typo fix, a minor addition), skip the summary refresh. Only touch docs where the body has shifted enough that the current blockquote actively misleads.
+- If the doc's structure has changed (added new sections that fundamentally change scope), don't just refresh the summary — suggest a broader restructure via `emdee move-doc` or `emdee split-doc`. Escalate to the user.
+
+## Reporting after the batch
+
+```
+Refreshed <N> summaries in <namespace>.
+Skipped <M> where drift was cosmetic.
+Flagged <K> for restructure (see notes).
+```

package/src/cli/auth-commands.ts

@@ -0,0 +1,72 @@
+// SPRINT-091: entrypoint for `emdee login | logout | whoami`.
+//
+// Shelled from bin/emdee.js via `npx tsx`. Kept separate from read-commands
+// so the auth flow's node:http server + browser-open logic doesn't get
+// loaded on every read invocation.
+
+import { parseArgs } from "node:util";
+import { login, deleteCreds, loadCreds, whoami, DEFAULT_HOST, NeedsLoginError } from "./auth";
+
+async function cmdLogin(argv: string[]): Promise<void> {
+  const { values } = parseArgs({ args: argv, options: { host: { type: "string" } }, strict: true });
+  const host = values.host ?? DEFAULT_HOST;
+  const creds = await login(host);
+  let email: string | null = null;
+  try {
+    const w = await whoami(creds);
+    email = w.email;
+  } catch {
+    // Non-fatal; login succeeded.
+  }
+  process.stdout.write(
+    `Logged in to ${host}${email ? ` as ${email}` : ""}.\n` +
+      `Credentials saved to ~/.config/emdee/credentials.json (mode 0600).\n`,
+  );
+}
+
+async function cmdLogout(): Promise<void> {
+  const removed = await deleteCreds();
+  process.stdout.write(removed ? "Logged out.\n" : "Already logged out.\n");
+}
+
+async function cmdWhoami(): Promise<void> {
+  const creds = await loadCreds();
+  if (!creds) {
+    process.stderr.write("Not logged in. Run `emdee login`.\n");
+    process.exit(1);
+  }
+  try {
+    const w = await whoami(creds);
+    process.stdout.write(`${w.email ?? "(no email on record)"}\nnamespace: ${w.namespace}\nhost: ${creds.host}\n`);
+  } catch (err) {
+    if (err instanceof NeedsLoginError) {
+      process.stderr.write(`${err.message}\n`);
+      process.exit(1);
+    }
+    throw err;
+  }
+}
+
+const [, , sub, ...rest] = process.argv;
+
+async function main(): Promise<void> {
+  switch (sub) {
+    case "login":
+      await cmdLogin(rest);
+      return;
+    case "logout":
+      await cmdLogout();
+      return;
+    case "whoami":
+      await cmdWhoami();
+      return;
+    default:
+      process.stderr.write(`unknown subcommand: ${sub ?? "(none)"}\nusage: emdee <login|logout|whoami> [--host URL]\n`);
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+});