@rubytech/create-realagent-code 0.1.23 → 0.1.26

package/payload/platform/plugins/cloudflare/scripts/tunnel-ingress.ts

@@ -0,0 +1,291 @@
+// Task 009 — Pure tunnel-ingress rendering + state I/O.
+//
+// Mirror of `samba-provision.ts`: pure decision functions in this file with
+// no side effects; `setup-tunnel.sh` orchestrates I/O around them. Invoked
+// from bash via `node --experimental-strip-types`. The CLI shim at the
+// bottom of this file takes a JSON spec on argv and prints rendered YAML
+// (or the requested state snippet) on stdout so the shell can `>` it into
+// the brand's config.yml or tunnel.state.
+//
+// Why a pure module:
+//  - The existing setup-tunnel.sh rebuilds config.yml from scratch every
+//    run. Adding SSH and SMB conditionally inline doubles the rewrite
+//    logic and makes it untestable. Extracting to a pure function with a
+//    test grid locks the YAML shape against future drift.
+//  - tunnel.state needs additive sshHostname / smbHostname fields so a
+//    re-run with no env vars rehydrates the ingress instead of silently
+//    dropping it. The persistence shape lives here so the test grid
+//    covers round-trip parity.
+//
+// Out of scope:
+//  - Cloudflare API calls (banned per `feedback_cf_api_total_eradication`).
+//  - Access policy creation (operator authors it in the dashboard).
+//  - DNS routing (the bash wrapper invokes `cloudflared tunnel route dns`).
+
+import { readFileSync, existsSync, appendFileSync } from "node:fs";
+
+// Task 054 — STREAM_LOG_PATH writer (Task 598/600 contract). The four CLI
+// subcommands invoked from setup-tunnel.sh (probe-samba, render-config,
+// render-state, action-req) emit a `phase=<cmd>-start` line on entry and
+// `phase=<cmd>-ok` / `phase=<cmd>-fail` on exit. Pattern ported verbatim
+// from list-cf-domains.ts:94-133: sticky-flag on first write failure to
+// avoid stderr spam if STREAM_LOG_PATH is unwritable; observability
+// failure must not mask the subcommand's real signal.
+let streamLogWriteFailed = false;
+
+function logPhase(line: string): void {
+  const streamLogPath = process.env.STREAM_LOG_PATH;
+  if (!streamLogPath || streamLogWriteFailed) return;
+  try {
+    appendFileSync(
+      streamLogPath,
+      `[${new Date().toISOString()}] [script:tunnel-ingress] ${line}\n`,
+    );
+  } catch (err) {
+    streamLogWriteFailed = true;
+    const detail = (err instanceof Error ? err.message : String(err))
+      .slice(0, 200)
+      .replace(/"/g, "'");
+    process.stderr.write(
+      `[tunnel-ingress] phase=stream-log-write-failed detail="${detail}"\n`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface IngressSpec {
+  tunnelId: string;
+  credentialsPath: string;
+  httpPort: number;
+  httpHostnames: string[];
+  sshHostname?: string | null;
+  smbHostname?: string | null;
+}
+
+export interface TunnelState {
+  tunnelId: string;
+  tunnelName: string;
+  domain: string;
+  configPath: string;
+  credentialsPath: string;
+  sshHostname?: string | null;
+  smbHostname?: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Pure renderer
+// ---------------------------------------------------------------------------
+
+/**
+ * Render config.yml from a fully-resolved IngressSpec. Order matters:
+ * cloudflared matches ingress rules top-to-bottom, so the catch-all
+ * `http_status:404` MUST be last. SSH and SMB are inserted between the
+ * HTTPS hostnames and the catch-all — they carry non-HTTP services, so
+ * placing them after HTTPS keeps the existing HTTP routing behaviour
+ * unchanged when no SSH/SMB hostname is configured.
+ */
+export function renderConfigYml(spec: IngressSpec): string {
+  const lines: string[] = [];
+  lines.push(`tunnel: ${spec.tunnelId}`);
+  lines.push(`credentials-file: ${spec.credentialsPath}`);
+  lines.push(`ingress:`);
+  for (const h of spec.httpHostnames) {
+    lines.push(`  - hostname: ${h}`);
+    lines.push(`    service: http://localhost:${spec.httpPort}`);
+  }
+  if (spec.sshHostname) {
+    lines.push(`  - hostname: ${spec.sshHostname}`);
+    lines.push(`    service: ssh://localhost:22`);
+  }
+  if (spec.smbHostname) {
+    lines.push(`  - hostname: ${spec.smbHostname}`);
+    lines.push(`    service: tcp://localhost:445`);
+  }
+  lines.push(`  - service: http_status:404`);
+  lines.push(``);
+  return lines.join("\n");
+}
+
+/**
+ * Render the tunnel.state JSON, preserving SSH/SMB hostnames as additive
+ * fields so re-runs can rehydrate them. The shape stays a superset of the
+ * pre-Task-009 JSON (tunnelId, tunnelName, domain, configPath,
+ * credentialsPath) — consumers that don't know about ssh/smb keep working.
+ */
+export function renderTunnelState(state: TunnelState): string {
+  const out: Record<string, string> = {
+    tunnelId: state.tunnelId,
+    tunnelName: state.tunnelName,
+    domain: state.domain,
+    configPath: state.configPath,
+    credentialsPath: state.credentialsPath,
+  };
+  if (state.sshHostname) out.sshHostname = state.sshHostname;
+  if (state.smbHostname) out.smbHostname = state.smbHostname;
+  return JSON.stringify(out, null, 2) + "\n";
+}
+
+/**
+ * Read an existing tunnel.state from disk, returning the persisted
+ * sshHostname / smbHostname if present. Used to rehydrate on re-runs
+ * where the operator did not pass the env vars again. Missing file or
+ * malformed JSON returns nulls — the caller decides whether to fail.
+ */
+export function readPersistedHostnames(statePath: string): {
+  sshHostname: string | null;
+  smbHostname: string | null;
+} {
+  if (!existsSync(statePath)) return { sshHostname: null, smbHostname: null };
+  try {
+    const raw = readFileSync(statePath, "utf8");
+    const parsed = JSON.parse(raw) as Partial<TunnelState>;
+    return {
+      sshHostname: typeof parsed.sshHostname === "string" ? parsed.sshHostname : null,
+      smbHostname: typeof parsed.smbHostname === "string" ? parsed.smbHostname : null,
+    };
+  } catch {
+    return { sshHostname: null, smbHostname: null };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Samba presence probe
+// ---------------------------------------------------------------------------
+
+/**
+ * Probe whether Task 034's per-brand Samba stanza exists in /etc/samba/smb.conf.
+ * The brand stanza header is `[<brand>]` at the start of a line (Task 034's
+ * `renderBrandStanza` output). Source of truth is the Pi filesystem, not
+ * brand.json — Samba is provisioned by the installer's post-install step,
+ * not declared up-front.
+ */
+export function probeSambaStanza(brand: string, smbConfPath = "/etc/samba/smb.conf"): boolean {
+  if (!existsSync(smbConfPath)) return false;
+  try {
+    const raw = readFileSync(smbConfPath, "utf8");
+    const re = new RegExp(`^\\[${escapeRegex(brand)}\\]\\s*$`, "m");
+    return re.test(raw);
+  } catch {
+    return false;
+  }
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// ---------------------------------------------------------------------------
+// ACTION REQUIRED block
+// ---------------------------------------------------------------------------
+
+/**
+ * Render the dashboard click-path the operator follows to author the Access
+ * policy. Same shape as the existing apex-CNAME ACTION REQUIRED block in
+ * setup-tunnel.sh. The script does NOT create the policy — Cloudflare API
+ * is banned (`feedback_cf_api_total_eradication`) and `cloudflared` CLI
+ * has no Access-application create subcommand. The operator clicks through
+ * Zero Trust → Access → Applications → Add → Self-hosted.
+ */
+export function renderAccessPolicyActionRequired(input: {
+  sshHostname?: string | null;
+  smbHostname?: string | null;
+  operatorEmail: string;
+}): string {
+  const hosts: Array<{ kind: "SSH" | "SMB"; hostname: string }> = [];
+  if (input.sshHostname) hosts.push({ kind: "SSH", hostname: input.sshHostname });
+  if (input.smbHostname) hosts.push({ kind: "SMB", hostname: input.smbHostname });
+  if (hosts.length === 0) return "";
+
+  const lines: string[] = [];
+  lines.push("");
+  lines.push("============================================================");
+  lines.push("ACTION REQUIRED — Cloudflare Zero Trust Access policy");
+  lines.push("============================================================");
+  for (const { kind, hostname } of hosts) {
+    lines.push(`  ${kind}: ${hostname}`);
+    lines.push(`    Cloudflare dashboard → Zero Trust → Access → Applications`);
+    lines.push(`    Add → Self-hosted`);
+    lines.push(`      Application name: ${hostname}`);
+    lines.push(`      Application domain: ${hostname}`);
+    lines.push(`      Policy → Action: Allow`);
+    lines.push(`      Include → Emails: ${input.operatorEmail}`);
+    lines.push("");
+  }
+  lines.push("Until each Access application is created, off-LAN clients see");
+  lines.push("Cloudflare's identity-rejection page and bytes never reach the Pi.");
+  lines.push("============================================================");
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// CLI shim
+// ---------------------------------------------------------------------------
+
+// Bash invokes this file with one of three subcommands:
+//   render-config <spec.json>          → stdout YAML
+//   render-state  <state.json>         → stdout JSON
+//   read-state    <state-path>         → stdout JSON {sshHostname,smbHostname}
+//   probe-samba   <brand> [smb.conf]   → exit 0 if present, 1 if absent
+//   action-req    <input.json>         → stdout ACTION REQUIRED block
+
+function readJsonArg(path: string): unknown {
+  const raw = readFileSync(path, "utf8");
+  return JSON.parse(raw);
+}
+
+const isCli =
+  typeof process !== "undefined" &&
+  Array.isArray(process.argv) &&
+  process.argv[1] !== undefined &&
+  /tunnel-ingress\.(ts|js|mjs|mts)$/.test(process.argv[1]);
+
+if (isCli) {
+  const [, , cmd, ...rest] = process.argv;
+  // Track which subcommands carry the Task 054 stream-log contract — for these
+  // we emit start/ok/fail phase pairs. Unknown subcommands and read-state are
+  // out of scope per the task (read-state has no setup-tunnel.sh caller line).
+  const instrumented = new Set(["probe-samba", "render-config", "render-state", "action-req"]);
+  if (instrumented.has(cmd)) logPhase(`phase=${cmd}-start`);
+  try {
+    if (cmd === "render-config") {
+      const spec = readJsonArg(rest[0]) as IngressSpec;
+      process.stdout.write(renderConfigYml(spec));
+      logPhase(`phase=${cmd}-ok`);
+    } else if (cmd === "render-state") {
+      const state = readJsonArg(rest[0]) as TunnelState;
+      process.stdout.write(renderTunnelState(state));
+      logPhase(`phase=${cmd}-ok`);
+    } else if (cmd === "read-state") {
+      const persisted = readPersistedHostnames(rest[0]);
+      process.stdout.write(JSON.stringify(persisted));
+    } else if (cmd === "probe-samba") {
+      const brand = rest[0];
+      const smbConf = rest[1] ?? "/etc/samba/smb.conf";
+      const present = probeSambaStanza(brand, smbConf);
+      logPhase(`phase=${cmd}-ok brand=${brand} present=${present}`);
+      process.exit(present ? 0 : 1);
+    } else if (cmd === "action-req") {
+      const input = readJsonArg(rest[0]) as {
+        sshHostname?: string | null;
+        smbHostname?: string | null;
+        operatorEmail: string;
+      };
+      process.stdout.write(renderAccessPolicyActionRequired(input));
+      logPhase(`phase=${cmd}-ok`);
+    } else {
+      process.stderr.write(`tunnel-ingress: unknown subcommand: ${cmd}\n`);
+      process.exit(2);
+    }
+  } catch (err) {
+    const msg = (err as Error).message;
+    if (instrumented.has(cmd)) {
+      const detail = msg.slice(0, 200).replace(/"/g, "'");
+      logPhase(`phase=${cmd}-fail error="${detail}"`);
+    }
+    process.stderr.write(`tunnel-ingress: ${msg}\n`);
+    process.exit(1);
+  }
+}

package/payload/platform/plugins/cloudflare/skills/setup-tunnel/SKILL.md

@@ -46,6 +46,48 @@ Example ({{productName}} on `maxy.bot` with a public subdomain and the `maxy.cha
 ~/setup-tunnel.sh maxy 19200 admin.maxy.bot public.maxy.bot maxy.chat
 ```
 
+### Optional SSH and SMB ingress (Task 009)
+
+The same script also wires the off-LAN SSH and SMB ingress when the
+corresponding hostnames are passed via environment variables (NOT positional
+argv — the positional contract is preserved for the form/endpoint caller):
+
+```
+SSH_HOSTNAME=ssh.maxy.bot \
+SMB_HOSTNAME=smb.maxy.bot \
+OPERATOR_EMAIL=joel@example.com \
+~/setup-tunnel.sh maxy 19200 admin.maxy.bot public.maxy.bot
+```
+
+Behaviour:
+
+- HTTPS hostnames are routed and config.yml rewritten FIRST. SSH and SMB
+  DNS routes happen in a second pass; a failure on SSH or SMB emits
+  `[tunnel-install] {ssh,smb}-ingress-deferred` and leaves the HTTPS
+  ingress durable (no rollback, no `exit 1`).
+- `SSH_HOSTNAME` adds an ingress entry `service: ssh://localhost:22`.
+- `SMB_HOSTNAME` adds `service: tcp://localhost:445`, gated on Task 034's
+  Samba stanza being present in `/etc/samba/smb.conf`. Absent stanza →
+  `[tunnel-install] smb-ingress-skipped reason=samba-not-provisioned` and
+  the SMB pass is skipped entirely.
+- Re-run with env vars unset rehydrates `sshHostname` / `smbHostname` from
+  `tunnel.state` so previously configured ingress is not silently dropped.
+- The Cloudflare Zero Trust Access policy that gates these hostnames is
+  authored by the operator in the dashboard — the script prints an
+  `ACTION REQUIRED` click-path with the resolved hostnames and operator
+  email (CF API is banned per `feedback_cf_api_total_eradication`). Phase
+  lines: `[tunnel-install] ssh-access-policy-required` and
+  `[tunnel-install] smb-access-policy-required` (named `-required`, not
+  `-set`, because the script does not create the policy).
+- Dry-run: `SETUP_TUNNEL_DRY_RUN=1` short-circuits before any cloudflared
+  mutation and prints the rendered `config.yml` and `tunnel.state` so the
+  operator can preview changes.
+
+The YAML and JSON rendering live in a pure Node helper at
+`platform/plugins/cloudflare/scripts/tunnel-ingress.ts`, unit-tested under
+`scripts/__tests__/tunnel-ingress.test.ts` and invoked from the shell via
+`node --experimental-strip-types`.
+
 The agent does not invoke the script directly during onboarding — the endpoint does. The agent's responsibility is to render the form and relay the endpoint's script output verbatim when `_componentDone` arrives. If an `ACTION REQUIRED` block appears, quote it exactly — the operator needs the specific dashboard instructions it contains.
 
 ### When the script exits non-zero

package/payload/platform/plugins/contacts/PLUGIN.md

@@ -2,15 +2,24 @@
 name: contacts
 description: "CRM contacts plugin. Provides contact-create, contact-lookup, contact-update, contact-delete, contact-list, contact-export, contact-erase, group-create, and group-manage tools for managing the customer contact graph and group conversations."
 tools:
-  - contact-create
-  - contact-lookup
-  - contact-update
-  - contact-delete
-  - contact-list
-  - contact-export
-  - contact-erase
-  - group-create
-  - group-manage
+  - name: contact-create
+    publicAllowlist: false
+  - name: contact-lookup
+    publicAllowlist: false
+  - name: contact-update
+    publicAllowlist: false
+  - name: contact-delete
+    publicAllowlist: false
+  - name: contact-list
+    publicAllowlist: false
+  - name: contact-export
+    publicAllowlist: false
+  - name: contact-erase
+    publicAllowlist: false
+  - name: group-create
+    publicAllowlist: false
+  - name: group-manage
+    publicAllowlist: false
 always: false
 embed: false
 metadata: {"platform":{}}

package/payload/platform/plugins/deep-research/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "deep-research",
-  "description": "Structured multi-source research workflow — query decomposition, search strategy, source evaluation, synthesis, and citation formatting. Uses Claude Code's native WebSearch and WebFetch tools.",
+  "description": "Structured multi-source research workflow: query decomposition, search strategy, source evaluation, synthesis, citation formatting, plus four named knowledge-worker skills (book-mirror, strategic-reading, academic-verify, data-research). Uses Claude Code's native WebSearch and WebFetch tools.",
   "version": "0.1.0",
   "author": {
     "name": "Rubytech LLC"

package/payload/platform/plugins/deep-research/PLUGIN.md

@@ -1,7 +1,13 @@
 ---
 name: deep-research
-description: "Structured multi-source research workflow — query decomposition, search strategy, source evaluation, synthesis, and citation formatting. Uses Claude Code's native WebSearch and WebFetch tools."
+description: "Structured multi-source research workflow: query decomposition, search strategy, source evaluation, synthesis, citation formatting, plus four named knowledge-worker skills (book-mirror, strategic-reading, academic-verify, data-research). Uses Claude Code's native WebSearch and WebFetch tools."
 tools: []
+skills:
+  - skills/deep-research/SKILL.md
+  - skills/book-mirror/SKILL.md
+  - skills/strategic-reading/SKILL.md
+  - skills/academic-verify/SKILL.md
+  - skills/data-research/SKILL.md
 always: false
 embed: false
 ---

package/payload/platform/plugins/deep-research/recipes/README.md

@@ -0,0 +1,36 @@
+# Recipes
+
+Recipes for the `data-research` skill. Each recipe is a YAML file that declares the field-by-field shape of an extraction, the source kinds it accepts, the validations to apply, and the graph target.
+
+A recipe is a contract. The owner reads the recipe and knows what `data-research` will write to the graph before it runs.
+
+## Recipe shape
+
+```yaml
+name: <recipe-name>
+description: One-line description of what this recipe extracts.
+source_kinds:
+  - email-thread       # one or more of: email-thread, web-page, pdf, text-file, form-submission
+fields:
+  - name: <field name>
+    type: string | number | date | boolean
+    required: true | false
+    validation:        # optional
+      min: <number>
+      max: <number>
+      pattern: <regex>
+      enum: [a, b, c]
+graph_target:
+  label: <Node label that must exist in the live Neo4j ontology>
+  identity:            # property names that together uniquely identify a row
+    - <field name>
+    - <field name>
+  relationships:       # optional
+    - type: <RELATIONSHIP_TYPE>
+      target_label: <Node label>
+      target_match: <field name>   # the field whose value resolves the target node via memory-search
+```
+
+## Updating a recipe
+
+Recipes are part of the plugin and are committed alongside the plugin. To add or change a recipe, the owner names the extraction in conversation, the operator drafts the YAML, the owner reviews it, and the file is saved here. The `data-research` skill loads recipes by name at run-time; it does not author or modify them inline.

package/payload/platform/plugins/deep-research/skills/academic-verify/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: academic-verify
+description: "Traces an academic or scientific claim through the publication chain to a primary source, checks for retraction, and returns one of four verdicts: verified, contradicted, retracted, or cannot be confirmed. Triggers when the owner says 'verify this study', 'is this paper real', 'check the citation', 'is X actually peer-reviewed'."
+---
+
+# Academic verify
+
+This skill is for claims that arrive as "studies show", "research suggests", or a named paper title. It traces the claim to the actual paper, the actual journal, and the actual conclusion of the source. It never says "verified" without a primary source URL.
+
+## When to run
+
+Run when the owner asks whether an academic or scientific claim is real. The trigger phrases are above. Also run when the owner repeats a strong claim attributed to "research" or "a study" and asks to check.
+
+## Inputs
+
+`claim` (the statement to verify) and optionally `source` (the citation the owner has, if any: a paper title, DOI, author and year, journal name, or a URL).
+
+If `claim` is missing, refuse. If `source` is missing, the skill will try to find the source from the claim wording.
+
+## Method
+
+1. **Find the originating paper.** If the owner provided a DOI or URL, fetch it. If they provided a paper title, search via `WebSearch` for the title in quotes, prioritising the journal's own site or a known repository (Google Scholar, PubMed, arXiv, OpenAlex). If they provided only the claim wording, search for the claim's distinctive phrasing in quotes.
+2. **Confirm the chain.** Pull these four facts from the source page:
+   - Paper title, authors, journal name, year.
+   - DOI (or arXiv ID, or PubMed ID).
+   - Peer-review status (peer-reviewed journal, preprint, working paper, conference abstract).
+   - The paper's own abstract or conclusion as written.
+3. **Check for retraction.** Search Retraction Watch and the journal's own page for a retraction notice. Capture the date and reason if found.
+4. **Cross-reference the claim against the paper.** Read the paper's abstract or conclusion. Compare the owner's claim wording to what the paper actually says. Decide one of four verdicts:
+   - **Verified.** The paper exists, is peer-reviewed (or clearly named as preprint), is not retracted, and the claim wording matches what the paper concludes.
+   - **Contradicted by source.** The paper exists but the claim wording overstates, reverses, or generalises beyond what the paper actually concludes.
+   - **Retracted.** The paper has been retracted. Name the date and reason.
+   - **Cannot be confirmed.** A search could not find a primary source, or the primary source is behind a paywall and only a secondary summary is available.
+5. **Return the verdict with the chain.** Verdict in the first sentence. Below it, the four facts from step 2. If retracted, the retraction details. If cannot-be-confirmed, name what was searched and where it stopped.
+
+## Output format
+
+```
+**Verdict.** <verified | contradicted by source | retracted | cannot be confirmed>
+
+**Source.**
+- Title: <paper title>
+- Authors: <list>
+- Journal: <journal name>, <year>
+- DOI: <DOI or other identifier>
+- Peer-review status: <peer-reviewed | preprint | working paper | conference abstract>
+- Primary source URL: <URL>
+
+**The paper concludes.** <one to three sentences, paraphrased tightly or quoted verbatim if wording matters>
+
+**The claim says.** <the owner's claim, verbatim>
+
+**Match.** <one paragraph on whether the claim faithfully represents the paper's conclusion. If contradicted, name the specific divergence.>
+
+(If retracted:)
+**Retraction.** <date, reason, retraction notice URL>
+```
+
+## Discipline
+
+- **Never say "verified" without a primary source URL in the output.** A claim is verified against the actual paper, not against a secondary summary.
+- **Paywalled abstracts.** If the abstract is behind a paywall, the verdict is "cannot be confirmed". Surface the paywall, do not infer from training memory what the paper says.
+- **Preprints.** A preprint is not the same as peer-reviewed. Surface the distinction explicitly; the owner may not want to act on a preprint result.
+- **Press release vs paper.** Press releases routinely overstate the paper's conclusions. If the chain goes paper → press release → claim, the verdict is usually "contradicted by source"; name the divergence.
+- **Author affiliation conflicts.** Surface known conflicts of interest from the paper's disclosure if present. Do not pretend they affect the verdict; they affect the owner's interpretation of the verdict.
+
+## Failure modes
+
+- **Search returns no candidates.** Verdict is "cannot be confirmed". Report the search terms tried.
+- **Multiple candidate papers.** Surface the top three and ask the owner to confirm which is the source.
+- **Search returns a retraction watch entry but no journal page.** Use the retraction watch entry as the primary source; the verdict is "retracted".
+
+## What this skill does not do
+
+It does not evaluate the paper's methodology or replicate the analysis. It checks whether the claim matches the source, not whether the source is correct. A flawed paper that is correctly cited returns "verified"; the owner is the one who decides whether the paper itself is sound.

package/payload/platform/plugins/deep-research/skills/book-mirror/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: book-mirror
+description: "Reads a book the owner provides (PDF, ePub, web link, or text), walks it chapter by chapter, and produces a personalised mirror that maps each chapter's claims to the owner's known context. Triggers when the owner says 'mirror this book', 'two-column analysis', 'how does this book apply to me', 'personalise this book against my business'."
+---
+
+# Book mirror
+
+This skill turns a book into a usable document by walking the chapters one at a time and asking, for each: "what does this say, and how does it apply to this specific owner". The output is a personalised pack the owner can read once and act on. It is grounded in the graph; the right-hand column is always specific to what the graph already knows about the owner.
+
+## When to run
+
+Run when the owner asks for a book to be applied to their situation. The trigger phrases are above. Do not run when the owner asks for a simple summary; a summary is what `deep-research` produces, and that is the right skill for that intent.
+
+## Inputs
+
+| Input | Meaning |
+|---|---|
+| `source` | The book. A path to a file in `$ACCOUNT_DIR`, a web URL, or pasted text. |
+| `anchor` | A node in the graph the book is being mirrored against. Usually the `LocalBusiness` node; can also be a named `Project` or `Goal`. |
+
+If the anchor is missing, ask for it in one sentence: "Mirror against the business, or a specific project?".
+
+## Method
+
+1. **Confirm the source.** If `source` is a file path, read it. If it is a URL, fetch it. If it is pasted text, work from the text directly. Reject sources that cannot be read; do not paraphrase a book the skill has not seen.
+2. **Identify the chapters.** Look for chapter headings in the text. If the book has none, segment by first-level headings or by every 2000 to 4000 words. Tell the owner the chapter count before starting.
+3. **For each chapter, build the two columns.**
+   - **Left.** A two-to-three-sentence summary of the chapter's actual claim. Quote verbatim only when the wording matters; otherwise paraphrase tightly.
+   - **Right.** A two-to-three-sentence note on how the claim applies to the anchor, grounded in graph specifics. Pull from `memory-search` against the anchor: the owner's business stage, recent obstacles, named projects, the LocalBusiness `businessType` schema. Name specific entities. Do not write "this applies to your business in general": that is jargon for "I have nothing specific to say".
+   - **Actions.** End each chapter with one or two concrete steps the owner could take this week. Use the imperative ("Call the photographer to confirm the brief for 14 Garth Road" rather than "Consider arranging photography").
+4. **Save the result.** Compose the whole pack as one `:KnowledgeDocument` with `:Section:Chapter` children per chapter. Link the document to the anchor node via `MIRRORS` (or `REFERENCES` if `MIRRORS` is not in the live ontology: call `maxy-graph-get_neo4j_schema` first).
+
+## Output format
+
+```
+# Mirror: <book title> against <anchor name>
+
+## Chapter 1: <chapter title>
+
+**The chapter.** <2-3 sentence summary>
+
+**For <anchor>.** <2-3 sentence application, grounded in graph specifics>
+
+**This week.** 
+- <one concrete action>
+- <one concrete action>
+
+---
+
+## Chapter 2: ...
+```
+
+Render the pack via `render-component name: document-editor` for owner review before saving. The owner can edit any chapter inline before the save. Once approved, write to the graph.
+
+## Length discipline
+
+Each chapter must fit on one screen (roughly 30 lines). If a chapter's claims need more, split the application across two or three chapter mirrors; do not pad. The whole pack should be readable in one sitting; a 20-chapter book becomes a 60-page pack only if every chapter genuinely earns its application.
+
+## Failure modes
+
+- **No chapters detectable and no headings.** Ask the owner to confirm the chunk size or to provide a chapter list.
+- **Anchor has thin graph context** (LocalBusiness with no recent activity, Project with no Tasks). Surface the gap: "the graph has limited context for <anchor>. The right column will be general where it should be specific. Continue?". Wait for confirmation.
+- **`memory-search` returns no useful results for the anchor**. Stop. The book cannot be mirrored against an empty anchor; tell the owner and recommend running `business-profile` or naming a different anchor.
+- **Source fetch fails.** Surface the error literally. Do not summarise from training memory.
+
+## What this skill does not do
+
+It does not summarise a book without an anchor; that is generic content, which `deep-research` can produce. It does not produce a study guide, a literature review, or a comparative essay. It produces one specific output: a personalised application of one book to one named entity in the graph.