@rubytech/create-maxy-code 0.1.499 → 0.1.500

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.499",
+  "version": "0.1.500",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

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

@@ -196,7 +196,7 @@ Tools are available via the `admin` MCP server.
 - `hooks/mcp-tool-missing.sh` — **PostToolUse hook on `mcp__.*` (directive 3).** Defence-in-depth for the `No such tool available: mcp__…` failure class that the name-binding is built to eliminate. Fires on any MCP tool call; no-op unless the `tool_response` carries `No such tool available` AND the qualified name resolves to a maxy plugin (read from the generated `hooks/lib/maxy-mcp-plugins.txt`). On a maxy match it logs one deterministic `[mcp-tool-missing] server=<server> tool=<tool>` line and exits 2 with a fixed envelope on stderr, so the agent relays a named server-unavailable failure instead of narrating "warming up" or blind-retrying. A missing non-maxy bridge tool (Playwright etc., upstream-owned) passes through (exit 0). The maxy-plugin list is regenerated and gate-diffed by `platform/scripts/check-canonical-tool-names.mjs`.
 - `hooks/post-tool-use-agent.sh` — **PostToolUse hook on `Agent`.** Drains any subagent hook-decision buffers under `~/.maxy-code/logs/hook-decisions/` modified since this parent's previous PostToolUse-Agent fire (cursor file keyed by parent session id), prints one `[hook-propagate]` line per record to stdout — Claude Code attaches the stdout as a `hook_success` attachment on the parent JSONL, making the records grep-queryable from the parent session alone. Rotates consumed buffers to `consumed/`. Emits one `[hook-propagate-census] parentSession=<…> subagentHooksObserved=<N> attachmentsEmitted=<M>` line per fire to stdout and server.log; `N != M` is the propagation regression signal. The companion emitter library `hooks/lib/hook-emit.sh` is sourced by `post-tool-use-agent.sh` and any other hook that records a block decision (4 KB stderr truncation, `truncated=true` set on the record).
 - `hooks/admin-authoring-observer.sh` — **PostToolUse hook on Write and Edit.** Observation only — never blocks; exits 0 on every path. Fires when the admin agent (not a specialist subagent — gated by `MAXY_SPECIALIST` env) writes or edits a file under `<accountDir>/output/`. Walks the session transcript from the latest real-user turn forward to detect any prior `Task` `tool_use` whose `subagent_type` starts with `specialists:`. Emits one stderr line `[admin-authoring] inline-write path=<rel> priorSpecialistSpawnInTurn=<true|false|unknown>`. A `false` value on a long-form prose file is the regression signal this hook was designed to make visible — the BioSymm proposal session (admin authored a customer-facing proposal inline despite content-producer being installed) is the failure mode this surfaces mechanically. Mechanical enforcement (refuse the write, force a re-spawn) is deferred per the task spec.
-- `hooks/prompt-optimiser-directive.sh` — **UserPromptSubmit hook.** Injects the standing prompt-optimiser restatement directive plus the per-turn three-tier routing ladder as `additionalContext`: **(1)** delegate to the specialist that owns the deliverable via the Agent tool — the brief states the outcome plus binding constraints, never lines/anchors/literal text; **(2)** only if none fits, load an admin-usable skill with `skill-load`; **(3)** only if neither fits, author inline — freestyle is the named last resort. Re-emits the full agent roster (`agents/admin/AGENTS.md`) and the full admin-usable skills list (`agents/admin/ADMIN-SKILLS.md`) every turn by reading the two generated files from the account dir (the hook fires with the account dir as cwd); it never walks the plugins tree per turn. Fail-open is **visible**: a missing list logs `[prompt-optimiser] missing=<AGENTS.md\|ADMIN-SKILLS.md> emitting-partial` to stderr and the ladder still injects. The trivial-turn skip (one-word confirmation, slash-command, direct continuation) is unchanged. **Staleness:** `ADMIN-SKILLS.md` is regenerated only by `setup-account.sh`; a plugin add/remove since the last setup leaves the list stale — compare `ADMIN-SKILLS.md` mtime against the newest `SKILL.md` mtime and re-run setup to refresh. The list generator is `platform/scripts/lib/admin-skills-bootstrap.sh`; it logs `[admin-skills] scanned=<N> admin-usable=<M> no-declaration=<K>` (failure signature: `admin-usable=0` while `scanned>0`, or any `missing-declaration` line). The directive also carries a standing CAPABILITY-QUESTIONS-ARE-OWNED-WORK clause (how-to / "do you have instructions for X" / config questions about platform features are answered from the owning specialist or plugin tool/reference, never from training memory), and the hook appends a durable `<ts> [prompt-optimiser-directive] injected len=<n> session=<id>` breadcrumb to `$LOG_DIR/prompt-optimiser-directive.log` so per-turn injection is greppable, not stderr-only. The directive is also **suppressed on native channel turns** — when the parsed `.prompt` starts with the `<channel source=` event marker, the hook logs `[prompt-optimiser-directive] skipped reason=channel-turn session=<id>` to stderr and exits without injecting, because the channel service already reframes the inbound into a select-and-dispatch turn (`composeAdminContent`, see `.docs/whatsapp-inbound-lifeline.md`). Marker-matched at start-of-prompt only, so an admin/Terminal prompt that merely mentions "channel" still gets the directive; fail-open injects if the prompt cannot be parsed.
+- `hooks/prompt-optimiser-directive.sh` — **UserPromptSubmit hook.** Injects the standing prompt-optimiser restatement directive plus the per-turn four-rung routing ladder as `additionalContext`: **(1)** delegate to the specialist that owns the deliverable via the Agent tool, where the brief states the outcome plus binding constraints, never lines/anchors/literal text; **(2)** only if none fits, load an admin-usable skill with `skill-load`; **(3)** only if the deliverable recurs and no specialist or skill owns it, author its owning skill via `skill-builder` (or `agent-builder` for a worker agent) and produce through it; **(4)** only if it is a genuine one-off, author inline as the named last resort. Re-emits the full agent roster (`agents/admin/AGENTS.md`) and the full admin-usable skills list (`agents/admin/ADMIN-SKILLS.md`) every turn by reading the two generated files from the account dir (the hook fires with the account dir as cwd); it never walks the plugins tree per turn. Fail-open is **visible**: a missing list logs `[prompt-optimiser] missing=<AGENTS.md\|ADMIN-SKILLS.md> emitting-partial` to stderr and the ladder still injects. The trivial-turn skip (one-word confirmation, slash-command, direct continuation) is unchanged. **Staleness:** `ADMIN-SKILLS.md` is regenerated only by `setup-account.sh`; a plugin add/remove since the last setup leaves the list stale — compare `ADMIN-SKILLS.md` mtime against the newest `SKILL.md` mtime and re-run setup to refresh. The list generator is `platform/scripts/lib/admin-skills-bootstrap.sh`; it logs `[admin-skills] scanned=<N> admin-usable=<M> no-declaration=<K>` (failure signature: `admin-usable=0` while `scanned>0`, or any `missing-declaration` line). The directive also carries a standing CAPABILITY-QUESTIONS-ARE-OWNED-WORK clause (how-to / "do you have instructions for X" / config questions about platform features are answered from the owning specialist or plugin tool/reference, never from training memory), and the hook appends a durable `<ts> [prompt-optimiser-directive] injected len=<n> session=<id>` breadcrumb to `$LOG_DIR/prompt-optimiser-directive.log` so per-turn injection is greppable, not stderr-only. The directive is also **suppressed on native channel turns** — when the parsed `.prompt` starts with the `<channel source=` event marker, the hook logs `[prompt-optimiser-directive] skipped reason=channel-turn session=<id>` to stderr and exits without injecting, because the channel service already reframes the inbound into a select-and-dispatch turn (`composeAdminContent`, see `.docs/whatsapp-inbound-lifeline.md`). Marker-matched at start-of-prompt only, so an admin/Terminal prompt that merely mentions "channel" still gets the directive; fail-open injects if the prompt cannot be parsed.
 - `hooks/preference-consult-directive.sh` — **UserPromptSubmit hook.** Injects a standing `<preference-adherence>` block naming the two-layer preference architecture (layer 1 the fixed block already in front of the agent every turn; layer 2 the account's own saved `Preference` records, read with `profile-read`, holding signature policy, header, naming and styling) and two directives: consult the relevant layer-2 preferences with `profile-read` before any customer-facing document deliverable, and store finished deliverables under `documents/` or the project folder because `output/` is scratch of last resort. Prompt-independent and always exit 0 (fail-open). Breadcrumb (stderr): `[pref-wrapper] op=inject`. This is the advisory companion to the `preference-consult-gate` hard gate.
 - `hooks/datetime-inject.sh` — **UserPromptSubmit hook.** Injects a fresh `<datetime>` block as `additionalContext` on every turn (`refresh=per-turn`), so the agent always has the current instant — date, time, timezone, weekday, and the raw UTC ISO — without hand-computing it and without depending on Claude Code's spawn-time "Today's date" line going stale. The instant is computed fresh each turn; the timezone is **not** computed here — it is the operator's own zone, resolved from their `UserProfile.timezone` on the graph once per admin spawn and stamped into `MAXY_ACCOUNT_TZ` (see `platform/services/claude-session-manager/src/account-timezone.ts`). When `MAXY_ACCOUNT_TZ` is empty (a non-admin turn, an unset profile timezone, or a neo4j hiccup at spawn) the block falls back to the server's own zone and labels the source, so a reader can always tell which clock the agent saw. This is the current-time surface the `datetime` skill points at. **Fail-open** on every path (missing `python3` or `node`, any formatting error → exit 0, empty stdout — the turn is never blocked). The hook appends `<ts> [datetime-inject] injected tz=<zone> source=<graph|server-fallback> refresh=per-turn session=<id>` to `$LOG_DIR/datetime-inject.log` so "did the agent have the right time this turn, and from which clock?" is answerable from logs without reproduction.
 - `hooks/prompt-optimiser-compliance.sh` — **Stop hook.** After each admin turn, reads the just-finished turn from `transcript_path` and appends `<ts> [prompt-optimiser-compliance] directive-fired no-route-taken session=<id8> prompt="<clip>"` to `$LOG_DIR/prompt-optimiser-directive.log` (and stderr) when the routing directive fired, the prompt was non-trivial (not a slash-command, not a one-word confirmation), and the turn took **no route** — no `Agent` dispatch, no `Skill` load, no `ToolSearch`, no `mcp__*` tool call. This is the standing compliance signal that surfaces the session-`da0b12d4` failure class (agent answers a capability question from memory) as a visible event instead of a silent stale answer. Directive-fired is detected by the marker `PROMPT-OPTIMISER DIRECTIVE` in the turn slice, so it is robust to the CC-version difference in how `UserPromptSubmit` `additionalContext` is recorded (`attachment`/`hook_success` vs `hook_additional_context`). **Known limitation:** "direct continuation of the prior turn" is not detectable from the transcript, so a continuation turn that legitimately needs no route can be flagged; treat the log as a review signal, not a gate. **Fail-open:** no python3, no `transcript_path`, or an unreadable transcript → exit 0, no output. Lives in the same log as the directive breadcrumb, so a single `grep` interleaves "fired" and "no-route" into one per-session timeline; cross-check via `platform/scripts/logs-read.sh <sessionKey>`. This is a lightweight transcript read, not a per-turn spawn (contrast the turn recorder below).

package/payload/platform/plugins/admin/hooks/__tests__/admin-authoring-observer.test.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+# Task 1961 — the classless inline-write line is the recurring-deliverable
+# arming signal.
+#
+# admin-authoring-observer.sh emits, on stderr, one line when the admin
+# process (MAXY_SPECIALIST empty) writes under <accountDir>/output/:
+#   [admin-authoring] inline-write path=<rel> priorSpecialistSpawnInTurn=<true|false|unknown>
+#
+# priorSpecialistSpawnInTurn=false is the arming signal: an inline output
+# write with no specialist dispatched earlier in the turn. This suite pins
+# fixture transcripts via ADMIN_AUTHORING_TRANSCRIPT_PATH and asserts:
+#   - false when the transcript has no specialists: Task after the last user turn
+#   - true  when it does
+#   - unknown when no transcript is available
+#   - no line at all for writes outside output/, or from a specialist process
+set -u
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/admin-authoring-observer.sh"
+[[ -x "$HOOK" ]] || { echo "FAIL: $HOOK not executable"; exit 1; }
+
+PASS=0; FAIL=0
+pass() { PASS=$((PASS+1)); echo "PASS: $1"; }
+fail() { FAIL=$((FAIL+1)); echo "FAIL: $1" >&2; }
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+ACCT="$TMP/account"
+mkdir -p "$ACCT/output"
+
+# Fixture transcripts.
+NO_SPECIALIST="$TMP/no-specialist.jsonl"
+cat >"$NO_SPECIALIST" <<'JSON'
+{"type":"user","message":{"role":"user","content":"draft a quote for the Smith job"}}
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"On it."}]}}
+JSON
+
+WITH_SPECIALIST="$TMP/with-specialist.jsonl"
+cat >"$WITH_SPECIALIST" <<'JSON'
+{"type":"user","message":{"role":"user","content":"draft a quote for the Smith job"}}
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"Task","input":{"subagent_type":"specialists:content-producer"}}]}}
+JSON
+
+# A Task whose subagent_type is not a specialist: must not count as a spawn.
+NON_SPECIALIST_TASK="$TMP/non-specialist-task.jsonl"
+cat >"$NON_SPECIALIST_TASK" <<'JSON'
+{"type":"user","message":{"role":"user","content":"draft a quote for the Smith job"}}
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"Task","input":{"subagent_type":"general-purpose"}}]}}
+JSON
+
+# A specialist dispatched in a PRIOR turn must not arm the current turn: the
+# hook walks forward only from the last real-user turn.
+PRIOR_TURN_SPECIALIST="$TMP/prior-turn-specialist.jsonl"
+cat >"$PRIOR_TURN_SPECIALIST" <<'JSON'
+{"type":"user","message":{"role":"user","content":"earlier request"}}
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"Task","input":{"subagent_type":"specialists:content-producer"}}]}}
+{"type":"user","message":{"role":"user","content":"draft a quote for the Smith job"}}
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"On it."}]}}
+JSON
+
+# input <tool_name> <file_path> — builds the PostToolUse payload the hook parses.
+mk_input() {
+  python3 -c '
+import json, sys
+print(json.dumps({
+  "hook_event_name": "PostToolUse",
+  "tool_name": sys.argv[1],
+  "tool_input": {"file_path": sys.argv[2]},
+  "transcript_path": ""
+}, separators=(",", ":")))
+' "$1" "$2"
+}
+
+# run <transcript-or-empty> <MAXY_SPECIALIST> <tool_name> <file_path> — fires the
+# hook from inside the account dir (its output/ scope keys off $PWD) and returns
+# stderr.
+run() {
+  local transcript="$1" specialist="$2" tool="$3" fp="$4"
+  ( cd "$ACCT" \
+    && mk_input "$tool" "$fp" \
+    | ADMIN_AUTHORING_TRANSCRIPT_PATH="$transcript" MAXY_SPECIALIST="$specialist" \
+      bash "$HOOK" 2>&1 1>/dev/null )
+}
+
+ARM_RE='\[admin-authoring\] inline-write path=output/quote\.html priorSpecialistSpawnInTurn='
+
+# 1. Arming signal: inline output write, no specialist in the turn.
+OUT=$(run "$NO_SPECIALIST" "" Write "output/quote.html")
+echo "$OUT" | grep -qE "${ARM_RE}false" \
+  && pass "arming: priorSpecialistSpawnInTurn=false on inline output write" \
+  || fail "arming false expected, got: $OUT"
+
+# 2. Owned: a specialist was dispatched earlier in the same turn.
+OUT=$(run "$WITH_SPECIALIST" "" Write "output/quote.html")
+echo "$OUT" | grep -qE "${ARM_RE}true" \
+  && pass "owned: priorSpecialistSpawnInTurn=true when specialist dispatched" \
+  || fail "true expected, got: $OUT"
+
+# 3. Unknown: no transcript available — line still fires, value is not the arming one.
+OUT=$(run "$TMP/does-not-exist.jsonl" "" Write "output/quote.html")
+echo "$OUT" | grep -qE "${ARM_RE}unknown" \
+  && pass "unknown: priorSpecialistSpawnInTurn=unknown with no transcript" \
+  || fail "unknown expected, got: $OUT"
+
+# 4. Edit is observed like Write.
+OUT=$(run "$NO_SPECIALIST" "" Edit "output/quote.html")
+echo "$OUT" | grep -qE "${ARM_RE}false" \
+  && pass "Edit under output/ is observed" \
+  || fail "Edit expected arming line, got: $OUT"
+
+# 4a. A non-specialist Task in the turn does not count as a spawn — still armed.
+OUT=$(run "$NON_SPECIALIST_TASK" "" Write "output/quote.html")
+echo "$OUT" | grep -qE "${ARM_RE}false" \
+  && pass "arming: non-specialist Task does not disarm" \
+  || fail "false expected for non-specialist Task, got: $OUT"
+
+# 4b. A specialist in a PRIOR turn does not disarm the current turn.
+OUT=$(run "$PRIOR_TURN_SPECIALIST" "" Write "output/quote.html")
+echo "$OUT" | grep -qE "${ARM_RE}false" \
+  && pass "arming: prior-turn specialist does not disarm current turn" \
+  || fail "false expected for prior-turn specialist, got: $OUT"
+
+# 5. Scope guard — write outside output/ emits no line.
+OUT=$(run "$NO_SPECIALIST" "" Write "notes/scratch.txt")
+echo "$OUT" | grep -q '\[admin-authoring\]' \
+  && fail "write outside output/ must emit nothing, got: $OUT" \
+  || pass "scope guard: write outside output/ emits no line"
+
+# 6. Scope guard — a specialist process (MAXY_SPECIALIST set) emits no line.
+OUT=$(run "$NO_SPECIALIST" "content-producer" Write "output/quote.html")
+echo "$OUT" | grep -q '\[admin-authoring\]' \
+  && fail "specialist process must emit nothing, got: $OUT" \
+  || pass "scope guard: specialist process emits no line"
+
+echo "----"
+echo "PASS=$PASS FAIL=$FAIL"
+[[ "$FAIL" -eq 0 ]]

package/payload/platform/plugins/admin/hooks/__tests__/prompt-optimiser-directive.test.sh

@@ -65,7 +65,7 @@ else
 fi
 rm -rf "$FAKEBIN"
 
-# Case 4 — both generated lists present: the ladder carries all three tiers, both
+# Case 4 — both generated lists present: the ladder carries all four rungs, both
 # full lists, and the relocated outcome-only-brief contract. The hook reads the
 # lists from $PWD/agents/admin, so run it from a temp account dir.
 WD=$(mktemp -d); mkdir -p "$WD/agents/admin"
@@ -78,11 +78,20 @@ if printf '%s' "$ctx" | grep -q "specialists:content-producer" \
    && printf '%s' "$ctx" | grep -qE '(^|[^0-9])1\)' \
    && printf '%s' "$ctx" | grep -qE '(^|[^0-9])2\)' \
    && printf '%s' "$ctx" | grep -qE '(^|[^0-9])3\)' \
+   && printf '%s' "$ctx" | grep -qE '(^|[^0-9])4\)' \
    && printf '%s' "$ctx" | grep -qiE "freestyle|last resort"; then
-  echo "PASS: both lists injected in three-tier ladder"; PASS=$((PASS+1))
+  echo "PASS: both lists injected in four-rung ladder"; PASS=$((PASS+1))
 else
   echo "FAIL: ladder/lists missing from additionalContext: $ctx" >&2; FAIL=$((FAIL+1))
 fi
+# Task 1959: recurring-deliverable rung sits before the freestyle last resort.
+if printf '%s' "$ctx" | grep -qi "skill-builder" \
+   && printf '%s' "$ctx" | grep -qiE "recurs|issues repeatedly|repeatable" \
+   && printf '%s' "$ctx" | grep -qi "agent-builder"; then
+  echo "PASS: recurring-deliverable rung present in ladder"; PASS=$((PASS+1))
+else
+  echo "FAIL: recurring-deliverable rung missing from ladder: $ctx" >&2; FAIL=$((FAIL+1))
+fi
 # Relocated outcome-only-brief contract.
 if printf '%s' "$ctx" | grep -qi "outcome" \
    && printf '%s' "$ctx" | grep -qi "binding constraints" \

package/payload/platform/plugins/admin/hooks/prompt-optimiser-directive.sh

@@ -1,13 +1,15 @@
 #!/usr/bin/env bash
 # UserPromptSubmit hook: inject the standing prompt-optimiser directive plus the
-# per-turn three-tier routing ladder as additionalContext on every turn, so the
+# per-turn four-rung routing ladder as additionalContext on every turn, so the
 # agent restates each non-trivial prompt and routes it before acting. Mirrors
 # doctrine.sh: emit hookSpecificOutput.additionalContext via python3, fail-open
 # with exit 0.
 #
 # The ladder ranks, in order: (1) delegate to a specialist that owns the
 # deliverable via the Agent tool; (2) only if none fits, load an admin-usable
-# skill; (3) only if neither fits, author inline — freestyle is the named last
+# skill; (3) only if the deliverable recurs and no specialist or skill owns it,
+# author its owning skill via skill-builder (or agent-builder) and produce
+# through it; (4) only if it is a genuine one-off, author inline as the last
 # resort. The full agent roster and admin-usable skills list are re-emitted every
 # turn by reading two generated files from the account dir; the hook never walks
 # the plugins tree per turn (Task 698).
@@ -102,7 +104,8 @@ IFS= read -r -d '' DIRECTIVE_MID <<'DIRECTIVE_EOF' || true
 DIRECTIVE_EOF
 
 IFS= read -r -d '' DIRECTIVE_TAIL <<'DIRECTIVE_EOF' || true
-3) Only if neither a specialist nor an admin skill fits, author it directly. Freestyle inline authoring is the last resort, not a peer of the two routes above.
+3) Only if neither a specialist nor an admin skill already owns it, decide whether the deliverable recurs. A deliverable the business issues repeatedly, or one the operator gives a fixed template, numbering, naming, or filing rule for, is authored once as its own skill: load skill-builder with skill-load (or agent-builder for a worker agent), create the owning skill, then produce the deliverable through it. This rung owns every repeatable business document or process; hand-building a recurring deliverable here is not a route.
+4) Only if the deliverable is a genuine one-off, author it directly. Freestyle inline authoring is the last resort, not a peer of the routes above.
 DIRECTIVE_EOF
 
 DIRECTIVE=$(printf '%s\n%s\n%s\n%s\n%s' \

package/payload/platform/plugins/admin/mcp/dist/index.js

@@ -5,7 +5,7 @@ import { z } from "zod";
 import { readFile, writeFile } from "node:fs/promises";
 import { resolve, join } from "node:path";
 import { execFile, execFileSync } from "node:child_process";
-import { appendFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { writeAdminEntry, removeAdminFromAccount, logUsersAudit, formatAuditRowIds } from "../../../../lib/admins-write/dist/index.js";
 import { setAccessPassword as setAccessPasswordHash, clearAccessPassword as clearAccessPasswordHash, accessPasswordCollides } from "../../../../lib/admin-access-password/dist/index.js";
 import { resolveCredentialTarget } from "./credential-identity.js";
@@ -20,6 +20,7 @@ import { homedir, hostname as osHostname } from "node:os";
 import QRCode from "qrcode";
 import { getSession, closeDriver } from "./lib/neo4j.js";
 import { findSkillOwners, searchSkills, computePluginReadHint, loadSkill, parseRequiredInputs, adminAuthoringSkillBlock, skillSlugFromReadArgs, AUTHORING_DISPATCH_HINT } from "./skill-resolution.js";
+import { storeSkillToAccount } from "./store-skill-core.js";
 import { resolvePublicHostname } from "./lib/public-hostname.js";
 import { resolveAdminHostname } from "./lib/admin-hostname.js";
 import { publishSite } from "./tools/publish-site.js";
@@ -1808,15 +1809,16 @@ eagerTool(server, "cpu-triage-read", "Read a cpu-triage run started by cpu-triag
     }
     return { content: [{ type: "text", text: JSON.stringify(out, null, 2) }] };
 });
-// operator-authored skills are written to disk as a plugin so the
-// existing plugin-manifest loader picks them up (parsePluginFrontmatter +
-// assemblePublicPluginContent + loadEmbeddedPlugins all read from
-// <PLATFORM_ROOT>/plugins/<dir>/). Canonical = <accountDir>/plugins/<plugin>
-// survives installer rmSync (data/ excluded); the mirror under
-// <PLATFORM_ROOT>/plugins/<plugin> is rehydrated at admin session start by
-// autoDeliverUserPlugins. The agent supplies pluginName/skillName/body —
-// path is computed by this tool from ACCOUNT_ID. Symmetric write counterpart
-// to plugin-read.
+// Task 1962 — operator-authored skills are written as a plugin under the
+// per-account root <accountDir>/plugins/<plugin>/ ONLY. That copy survives the
+// installer wipe (data/ is excluded) and is loaded directly by the spawn
+// manifest (computeActivePlugins) and the admin skill resolvers, which walk the
+// account root. Nothing is written to the immutable PLATFORM_ROOT/plugins tree
+// (chattr +i) and there is no platform mirror. The write+resolve core lives in
+// store-skill-core.ts and fails closed if the written skill does not resolve,
+// so success is never reported for a skill that cannot load. The agent supplies
+// pluginName/skillName/body — the path is computed from ACCOUNT_ID. Symmetric
+// write counterpart to plugin-read.
 eagerTool(server, "store-skill", "Save an operator-authored skill on disk as part of an admin-managed plugin. " +
     "The skill becomes immediately discoverable by the admin agent (and the public agent if publicEmbed=true). " +
     "Path is computed internally from the active account; the agent supplies content + names only. " +
@@ -1850,97 +1852,31 @@ eagerTool(server, "store-skill", "Save an operator-authored skill on disk as par
         }
     }
     const accountDir = getAccountDir();
-    const canonicalPluginDir = resolve(accountDir, "plugins", pluginName);
-    const mirrorPluginDir = resolve(PLATFORM_ROOT, "plugins", pluginName);
-    const canonicalPluginMd = resolve(canonicalPluginDir, "PLUGIN.md");
-    const mirrorPluginMd = resolve(mirrorPluginDir, "PLUGIN.md");
-    // Collision: mirror dir exists from a shipped plugin (no canonical mirror).
-    // Refuse rather than silently shadow.
-    if (existsSync(mirrorPluginMd) && !existsSync(canonicalPluginMd)) {
-        console.error(`[store-skill] ERROR pluginName=${pluginName} skillName=${skillName} reason=collision-with-shipped path=${mirrorPluginDir}`);
-        return { content: [{ type: "text", text: `pluginName "${pluginName}" collides with a shipped plugin. Choose a different pluginName.` }], isError: true };
-    }
-    const skillDir = resolve(canonicalPluginDir, "skills", skillName);
-    const action = existsSync(resolve(skillDir, "SKILL.md")) ? "overwrite" : "create";
-    try {
-        mkdirSync(canonicalPluginDir, { recursive: true });
-        // Compose PLUGIN.md only on first write. embed=["admin","public"] +
-        // optional=false matches assemblePublicPluginContent / loadEmbeddedPlugins
-        // expectations. metadata is single-line JSON (parsePluginFrontmatter at
-        // plugin-manifest.ts:67 expects single-line) — multi-line silently falls
-        // back to platform={}.
-        if (!existsSync(canonicalPluginMd)) {
-            const pluginMd = `---
-name: ${pluginName}
-description: "Operator-authored plugin"
-tools: []
-hidden: []
-requires: []
-metadata: {"platform":{"embed":["admin","public"],"optional":false}}
----
-
-# ${pluginName}
-
-Operator-authored plugin. Skills under \`skills/\` were created via the admin skill-builder.
-`;
-            writeFileSync(canonicalPluginMd, pluginMd);
-        }
-        // Reset skill dir before write so removed reference files don't linger.
-        if (existsSync(skillDir)) {
-            rmSync(skillDir, { recursive: true, force: true });
-        }
-        mkdirSync(skillDir, { recursive: true });
-        // Normalise description — strip newlines and tabs to keep YAML
-        // frontmatter on a single line. parsePluginFrontmatter uses a
-        // single-line regex; an embedded newline (or `\n---\n`) would
-        // otherwise corrupt the frontmatter parse and silently drop body
-        // content from the agent prompt.
-        const singleLineDescription = description.replace(/[\r\n\t]+/g, " ").trim();
-        const escapedDescription = singleLineDescription.replace(/"/g, '\\"');
-        const skillMd = `---
-name: ${skillName}
-description: "${escapedDescription}"
-publicEmbed: ${publicEmbed}
----
-
-${body}
-`;
-        writeFileSync(resolve(skillDir, "SKILL.md"), skillMd);
-        let refCount = 0;
-        if (references.length > 0) {
-            const refsDir = resolve(skillDir, "references");
-            mkdirSync(refsDir, { recursive: true });
-            for (const ref of references) {
-                writeFileSync(resolve(refsDir, ref.filename), ref.content);
-                refCount++;
-            }
-        }
-        // Write the `.user-mirror` marker to CANONICAL first — cpSync will
-        // carry it into the platform-side mirror as part of the same recursive
-        // copy. This eliminates the post-cpSync writeFileSync race: if cpSync
-        // succeeds, the marker is already in target; if cpSync fails partway,
-        // canonical's marker is intact and the next autoDeliverUserPlugins
-        // call retries the copy. autoDeliverUserPlugins relies on the marker
-        // arriving with the source tree — never writes its own marker.
-        writeFileSync(resolve(canonicalPluginDir, ".user-mirror"), `pluginName=${pluginName}\nsource=${canonicalPluginDir}\n`);
-        // Mirror to <PLATFORM_ROOT>/plugins/<pluginName>/ so the change is
-        // visible to the loader without a session restart.
-        mkdirSync(mirrorPluginDir, { recursive: true });
-        cpSync(canonicalPluginDir, mirrorPluginDir, { recursive: true, force: true });
-        const bodyBytes = Buffer.byteLength(body, "utf-8");
-        console.log(`[store-skill] write pluginName=${pluginName} skillName=${skillName} publicEmbed=${publicEmbed} path=${canonicalPluginDir} bodyBytes=${bodyBytes} referenceCount=${refCount} action=${action}`);
-        return {
-            content: [{
-                    type: "text",
-                    text: `Skill "${skillName}" saved to plugin "${pluginName}" (${action}). publicEmbed=${publicEmbed}, references=${refCount}. Active immediately for the admin agent${publicEmbed ? "; surfaces in the public agent on next session start" : ""}.`,
-                }],
-        };
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.error(`[store-skill] ERROR pluginName=${pluginName} skillName=${skillName} reason=${msg.slice(0, 120)} path=${canonicalPluginDir}`);
-        return { content: [{ type: "text", text: `Failed to write skill: ${msg}` }], isError: true };
-    }
+    const result = await storeSkillToAccount({
+        accountDir,
+        platformRoot: PLATFORM_ROOT,
+        pluginName,
+        skillName,
+        description,
+        publicEmbed,
+        body,
+        references,
+    });
+    if (!result.ok) {
+        const isCollision = result.reason === "collision-with-shipped";
+        console.error(`[store-skill] op=store-skill root=account path=${result.canonicalPluginDir} resolved=false reason=${result.reason} pluginName=${pluginName} skillName=${skillName} detail=${result.detail.slice(0, 120)}`);
+        const text = isCollision
+            ? `pluginName "${pluginName}" collides with a shipped plugin. Choose a different pluginName.`
+            : `Skill "${skillName}" was written to "${pluginName}" but did not register: ${result.detail}. Not activating.`;
+        return { content: [{ type: "text", text }], isError: true };
+    }
+    console.log(`[store-skill] op=store-skill root=account path=${result.canonicalPluginDir} resolved=true pluginName=${pluginName} skillName=${skillName} publicEmbed=${publicEmbed} bodyBytes=${result.bodyBytes} referenceCount=${result.refCount} action=${result.action}`);
+    return {
+        content: [{
+                type: "text",
+                text: `Skill "${skillName}" saved to plugin "${pluginName}" (${result.action}). publicEmbed=${publicEmbed}, references=${result.refCount}. Active immediately for the admin agent${publicEmbed ? "; surfaces in the public agent on next session start" : ""}.`,
+            }],
+    };
 });
 eagerTool(server, "plugin-read", "Read a plugin definition (PLUGIN.md) or one of its reference files.", {
     pluginName: z.string().describe("Name of the plugin directory (e.g. 'sales', 'business-assistant')"),
@@ -1960,14 +1896,23 @@ eagerTool(server, "plugin-read", "Read a plugin definition (PLUGIN.md) or one of
             console.log(`[admin-skill-gate] role=admin skill=${authoringSlug} decision=block reason=content-producer-owned`);
             return { content: [{ type: "text", text: AUTHORING_DISPATCH_HINT }], isError: true };
         }
-        const pluginPath = resolve(PLATFORM_ROOT, "plugins", pluginName, resolvedFile);
+        // Task 1962 — operator-authored plugins live under the account root, not
+        // the platform tree. Prefer the platform copy; fall back to the account
+        // root so an operator plugin's PLUGIN.md / SKILL.md / references resolve.
+        const accountPluginsDir = resolve(getAccountDir(), "plugins");
+        const platformPath = resolve(PLATFORM_ROOT, "plugins", pluginName, resolvedFile);
+        const accountPath = resolve(accountPluginsDir, pluginName, resolvedFile);
+        const pluginPath = existsSync(platformPath) ? platformPath : accountPath;
+        const pluginRootDir = existsSync(platformPath)
+            ? resolve(PLATFORM_ROOT, "plugins", pluginName)
+            : resolve(accountPluginsDir, pluginName);
         if (!existsSync(pluginPath)) {
             // when the agent's pluginName/file combination misses
             // a skill that DOES live under `plugins/*/skills/<slug>/SKILL.md`,
             // surface the corrected pluginName AND the canonical file path so
             // the next call is deterministic. Both wrong-`file` and wrong-`pluginName`
             // shapes feed through `computePluginReadHint`.
-            const hint = computePluginReadHint(PLATFORM_ROOT, pluginName, resolvedFile);
+            const hint = computePluginReadHint(PLATFORM_ROOT, pluginName, resolvedFile, accountPluginsDir);
             const hintText = hint ? ` Did you mean pluginName="${hint.pluginName}", file="${hint.file}"?` : "";
             console.log(`[plugin-read] ${pluginName}/${resolvedFile} not-found hint=${hint ? hint.pluginName : "none"}`);
             return {
@@ -1984,7 +1929,7 @@ eagerTool(server, "plugin-read", "Read a plugin definition (PLUGIN.md) or one of
         // Append file inventory on default calls (PLUGIN.md) so agents can discover
         // skill and reference paths without guessing
         if (resolvedFile === "PLUGIN.md") {
-            const pluginRoot = resolve(PLATFORM_ROOT, "plugins", pluginName);
+            const pluginRoot = pluginRootDir;
             const skills = [];
             const references = [];
             const scanDir = (base, prefix, target) => {
@@ -2044,7 +1989,7 @@ lifelineTool(server, "skill-find", "Find which plugin owns a skill by name. Walk
     if (!ACCOUNT_ID)
         return refuseNoAccount("skill-find");
     const start = Date.now();
-    const result = findSkillOwners(PLATFORM_ROOT, skillName);
+    const result = findSkillOwners(PLATFORM_ROOT, skillName, resolve(getAccountDir(), "plugins"));
     const ms = Date.now() - start;
     console.log(`[skill-find] skillName=${skillName} result=${result.status} candidates=${result.candidates.length} ms=${ms}`);
     if (result.status === "unique") {
@@ -2085,7 +2030,7 @@ eagerTool(server, "skill-search", "Find skills by free-text intent when you do n
     if (!ACCOUNT_ID)
         return refuseNoAccount("skill-search");
     const start = Date.now();
-    const hits = searchSkills(PLATFORM_ROOT, query);
+    const hits = searchSkills(PLATFORM_ROOT, query, 5, resolve(getAccountDir(), "plugins"));
     const ms = Date.now() - start;
     const top = hits.length > 0 ? `${hits[0].pluginName}:${hits[0].skillName}` : "none";
     console.log(`[skill-search] query=${JSON.stringify(query)} hits=${hits.length} top=${top} ms=${ms}`);
@@ -2134,7 +2079,7 @@ eagerTool(server, "skill-load", "Load a plugin skill's SKILL.md body by skill na
     }
     const start = Date.now();
     try {
-        const outcome = await loadSkill(PLATFORM_ROOT, skillName);
+        const outcome = await loadSkill(PLATFORM_ROOT, skillName, resolve(getAccountDir(), "plugins"));
         if (outcome.status === "ambiguous") {
             const ms = Date.now() - start;
             console.log(`[skill-load] skillName=${skillName} result=ambiguous pluginName=none file=none bodyBytes=0 ms=${ms}`);