@aisystemresources/emdee 0.1.2 → 0.2.0

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);
+});

package/src/cli/auth.ts

@@ -0,0 +1,215 @@
+// SPRINT-091: CLI auth — PKCE loopback OAuth against emdee.tech.
+//
+// Follows RFC 8252 (OAuth 2.0 for native apps) + dynamic client registration
+// via /oauth/register (matches Codex + Claude Code patterns already in use).
+// Credentials land in ~/.config/emdee/credentials.json at 0600.
+//
+// Token has a 30-day TTL and there is no refresh grant on the server today,
+// so credentials are simple: access_token + client_id + host + saved_at. When
+// a token expires, the CLI surfaces `run 'emdee login'` — same UX as Codex.
+
+import { createHash, randomBytes } from "node:crypto";
+import { readFile, writeFile, mkdir, unlink, chmod, stat } from "node:fs/promises";
+import { createServer, type Server } from "node:http";
+import { spawn } from "node:child_process";
+import path from "node:path";
+import os from "node:os";
+
+const CREDS_DIR = path.join(os.homedir(), ".config", "emdee");
+const CREDS_PATH = path.join(CREDS_DIR, "credentials.json");
+export const DEFAULT_HOST = process.env.EMDEE_CLOUD_URL ?? "https://emdee.tech";
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+
+export interface Credentials {
+  access_token: string;
+  client_id: string;
+  host: string;
+  saved_at: number;
+}
+
+export class NeedsLoginError extends Error {
+  constructor(message = "Run `emdee login` first.") {
+    super(message);
+    this.name = "NeedsLoginError";
+  }
+}
+
+// PKCE helpers per RFC 7636.
+function base64url(buf: Buffer): string {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function generatePkce(): { verifier: string; challenge: string } {
+  const verifier = base64url(randomBytes(32));
+  const challenge = base64url(createHash("sha256").update(verifier).digest());
+  return { verifier, challenge };
+}
+
+// File I/O ------------------------------------------------------------------
+
+export async function loadCreds(): Promise<Credentials | null> {
+  try {
+    const text = await readFile(CREDS_PATH, "utf8");
+    return JSON.parse(text) as Credentials;
+  } catch {
+    return null;
+  }
+}
+
+async function saveCreds(creds: Credentials): Promise<void> {
+  await mkdir(CREDS_DIR, { recursive: true });
+  await writeFile(CREDS_PATH, JSON.stringify(creds, null, 2), "utf8");
+  await chmod(CREDS_PATH, 0o600);
+}
+
+export async function deleteCreds(): Promise<boolean> {
+  try {
+    await stat(CREDS_PATH);
+    await unlink(CREDS_PATH);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Browser open (best-effort per platform) -----------------------------------
+
+function openBrowser(url: string): void {
+  const platform = process.platform;
+  const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
+  try {
+    spawn(cmd, [url], { stdio: "ignore", detached: true }).unref();
+  } catch {
+    // Best-effort — user can copy the URL if this fails.
+  }
+}
+
+// Dynamic client registration ----------------------------------------------
+
+async function registerClient(host: string, redirectUri: string): Promise<string> {
+  const res = await fetch(`${host}/oauth/register`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      client_name: `emdee-cli (${os.hostname()})`,
+      redirect_uris: [redirectUri],
+    }),
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`oauth register failed: ${res.status} ${body}`);
+  }
+  const body = (await res.json()) as { client_id: string };
+  return body.client_id;
+}
+
+// Main login flow ----------------------------------------------------------
+
+export async function login(host: string = DEFAULT_HOST): Promise<Credentials> {
+  const { verifier, challenge } = generatePkce();
+  const state = base64url(randomBytes(16));
+
+  // 1. Bind loopback server on an OS-assigned port so we know the redirect_uri
+  //    BEFORE we register the client + open the browser.
+  let capturedCode: string | null = null;
+  let capturedState: string | null = null;
+  const server: Server = createServer((req, res) => {
+    if (!req.url) return;
+    const u = new URL(req.url, "http://localhost");
+    if (u.pathname !== "/callback") {
+      res.statusCode = 404;
+      res.end();
+      return;
+    }
+    capturedCode = u.searchParams.get("code");
+    capturedState = u.searchParams.get("state");
+    res.setHeader("Content-Type", "text/html; charset=utf-8");
+    res.end(
+      `<!doctype html><html><body style="font-family:system-ui;padding:2em;text-align:center"><h2>${capturedCode ? "Login complete" : "Login failed"}</h2><p>You can close this tab and return to the terminal.</p></body></html>`
+    );
+    // Give the browser a beat to render the response before shutting the socket.
+    setTimeout(() => server.close(), 100);
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => resolve());
+  });
+  const port = (server.address() as { port: number }).port;
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+
+  // 2. Register a fresh client for this login (matches Codex's per-session pattern).
+  const clientId = await registerClient(host, redirectUri);
+
+  // 3. Open browser to authorize.
+  const authorizeUrl = new URL(`${host}/oauth/authorize`);
+  authorizeUrl.searchParams.set("response_type", "code");
+  authorizeUrl.searchParams.set("client_id", clientId);
+  authorizeUrl.searchParams.set("redirect_uri", redirectUri);
+  authorizeUrl.searchParams.set("code_challenge", challenge);
+  authorizeUrl.searchParams.set("code_challenge_method", "S256");
+  authorizeUrl.searchParams.set("state", state);
+  authorizeUrl.searchParams.set("scope", "mcp");
+  const authUrl = authorizeUrl.toString();
+  console.error(`Opening browser to authorize:\n${authUrl}\n`);
+  openBrowser(authUrl);
+
+  // 4. Wait for callback (or timeout).
+  const code = await new Promise<string>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      server.close();
+      reject(new Error("Login timed out. Retry with `emdee login`."));
+    }, LOGIN_TIMEOUT_MS);
+    server.on("close", () => {
+      clearTimeout(timer);
+      if (!capturedCode) return reject(new Error("Login was cancelled."));
+      if (capturedState !== state) return reject(new Error("State mismatch — possible CSRF, aborted."));
+      resolve(capturedCode);
+    });
+  });
+
+  // 5. Exchange the code for an access token.
+  const tokenRes = await fetch(`${host}/oauth/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: redirectUri,
+      client_id: clientId,
+      code_verifier: verifier,
+    }).toString(),
+  });
+  if (!tokenRes.ok) {
+    const body = await tokenRes.text().catch(() => "");
+    throw new Error(`token exchange failed: ${tokenRes.status} ${body}`);
+  }
+  const tokenBody = (await tokenRes.json()) as { access_token: string };
+
+  const creds: Credentials = {
+    access_token: tokenBody.access_token,
+    client_id: clientId,
+    host,
+    saved_at: Date.now(),
+  };
+  await saveCreds(creds);
+  return creds;
+}
+
+// Whoami — hits the new /api/whoami endpoint --------------------------------
+
+export interface WhoamiPayload {
+  namespace: string;
+  email: string | null;
+}
+
+export async function whoami(creds: Credentials): Promise<WhoamiPayload> {
+  const res = await fetch(`${creds.host}/api/whoami`, {
+    headers: { Authorization: `Bearer ${creds.access_token}` },
+  });
+  if (res.status === 401) throw new NeedsLoginError();
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`whoami failed: ${res.status} ${body}`);
+  }
+  return (await res.json()) as WhoamiPayload;
+}