trybeacon 0.1.64 → 0.1.66

package/dist/bin/uninstall.js

@@ -1,22 +1,22 @@
 #!/usr/bin/env bun
 // @bun
-var gZ=Object.defineProperty;var EZ=(Q)=>Q;function IZ(Q,Z){this[Q]=EZ.bind(null,Z)}var PQ=(Q,Z)=>{for(var $ in Z)gZ(Q,$,{get:Z[$],enumerable:!0,configurable:!0,set:IZ.bind(Z,$)})};var M=(Q,Z)=>()=>(Q&&(Z=Q(Q=0)),Z);var _0=1500,k0=480000,S0=1800000,k=3600000,h0=3000;var cQ=()=>{};var xQ={};PQ(xQ,{removeRepoAssets:()=>vQ,installRefreshSkill:()=>AZ,installPlanSkill:()=>bZ,installInitSkill:()=>DZ,installCodexRepoSkills:()=>yZ,ensureWorkflowDoc:()=>LZ,ensureMcp:()=>_Z,auditRepo:()=>kZ,REFRESH_SKILL:()=>NQ,PLAN_SKILL:()=>nQ,INIT_SKILL:()=>BQ});import{existsSync as T,mkdirSync as h,readFileSync as N,rmSync as S,writeFileSync as H}from"fs";import{join as U}from"path";function DZ(Q){let Z=U(Q,".claude","skills","beacon-init");h(Z,{recursive:!0});let $=U(Z,"SKILL.md");return H($,BQ),$}function AZ(Q){let Z=U(Q,".claude","skills","beacon-refresh");h(Z,{recursive:!0});let $=U(Z,"SKILL.md");return H($,NQ),$}function bZ(Q){let Z=U(Q,".claude","skills","beacon-plan");h(Z,{recursive:!0});let $=U(Z,"SKILL.md");return H($,nQ),$}function yZ(Q){let Z=[];for(let $ of OZ){let J=U(Q,".agents","skills",$.name);h(J,{recursive:!0});let Y=U(J,"SKILL.md");H(Y,$.body()),Z.push(Y)}return Z}function LZ(Q){let Z=U(Q,"AGENTS.md"),$="";try{$=N(Z,"utf8")}catch{}let J=new RegExp(`${m}[\\s\\S]*?${GQ}`);$=J.test($)?$.replace(J,lQ):`${$.trim()}
+var EZ=Object.defineProperty;var DZ=(Q)=>Q;function IZ(Q,Z){this[Q]=DZ.bind(null,Z)}var jQ=(Q,Z)=>{for(var $ in Z)EZ(Q,$,{get:Z[$],enumerable:!0,configurable:!0,set:IZ.bind(Z,$)})};var M=(Q,Z)=>()=>(Q&&(Z=Q(Q=0)),Z);var S0=1500,h0=480000,m0=1800000,S=3600000,p0=3000;var cQ=()=>{};var xQ={};jQ(xQ,{removeRepoAssets:()=>NQ,installRefreshSkill:()=>OZ,installPlanSkill:()=>AZ,installInitSkill:()=>bZ,installExplainSkill:()=>yZ,installCodexRepoSkills:()=>LZ,ensureWorkflowDoc:()=>_Z,ensureMcp:()=>SZ,auditRepo:()=>hZ,REFRESH_SKILL:()=>GQ,PLAN_SKILL:()=>nQ,INIT_SKILL:()=>PQ,EXPLAIN_SKILL:()=>tQ});import{existsSync as T,mkdirSync as g,readFileSync as G,rmSync as h,writeFileSync as H}from"fs";import{join as X}from"path";function bZ(Q){let Z=X(Q,".claude","skills","beacon-init");g(Z,{recursive:!0});let $=X(Z,"SKILL.md");return H($,PQ),$}function OZ(Q){let Z=X(Q,".claude","skills","beacon-refresh");g(Z,{recursive:!0});let $=X(Z,"SKILL.md");return H($,GQ),$}function AZ(Q){let Z=X(Q,".claude","skills","beacon-plan");g(Z,{recursive:!0});let $=X(Z,"SKILL.md");return H($,nQ),$}function yZ(Q){let Z=X(Q,".claude","skills","beacon-explain");g(Z,{recursive:!0});let $=X(Z,"SKILL.md");return H($,tQ),$}function LZ(Q){let Z=[];for(let $ of kZ){let J=X(Q,".agents","skills",$.name);g(J,{recursive:!0});let Y=X(J,"SKILL.md");H(Y,$.body()),Z.push(Y)}return Z}function _Z(Q){let Z=X(Q,"AGENTS.md"),$="";try{$=G(Z,"utf8")}catch{}let J=new RegExp(`${m}[\\s\\S]*?${vQ}`);$=J.test($)?$.replace(J,lQ):`${$.trim()}
 
 ${lQ}
 `.trimStart(),H(Z,$.endsWith(`
 `)?$:`${$}
-`);let Y=U(Q,"CLAUDE.md"),V="";try{V=N(Y,"utf8")}catch{}if(!/@AGENTS\.md/.test(V))H(Y,`${V?`${V.trim()}
+`);let Y=X(Q,"CLAUDE.md"),V="";try{V=G(Y,"utf8")}catch{}if(!/@AGENTS\.md/.test(V))H(Y,`${V?`${V.trim()}
 
 `:""}@AGENTS.md
-`)}function _Z(Q){let Z=U(Q,".mcp.json"),$={};try{$=JSON.parse(N(Z,"utf8"))}catch{}$.mcpServers=$.mcpServers??{};let J=$.mcpServers.beacon;if(J){if(!J.timeout||J.timeout<k)return J.timeout=k,H(Z,JSON.stringify($,null,2)+`
-`),{path:Z,added:!1,updated:!0};return{path:Z,added:!1,updated:!1}}return $.mcpServers.beacon={command:"beacon",args:["mcp"],timeout:k},H(Z,JSON.stringify($,null,2)+`
-`),{path:Z,added:!0,updated:!1}}function kZ(Q){let Z=U(Q,".mcp.json"),$=!1;try{$=!!JSON.parse(N(Z,"utf8")).mcpServers?.beacon}catch{}let J=!1;try{J=N(U(Q,"AGENTS.md"),"utf8").includes(m)}catch{}let Y=!1;try{Y=/@AGENTS\.md/.test(N(U(Q,"CLAUDE.md"),"utf8"))}catch{}return{repo:Q,mcpRegistered:$,agentsMdBlock:J,claudeMdImport:Y,skills:{"beacon-init":T(U(Q,".claude","skills","beacon-init","SKILL.md")),"beacon-refresh":T(U(Q,".claude","skills","beacon-refresh","SKILL.md"))},codexSkills:{"beacon-init":T(U(Q,".agents","skills","beacon-init","SKILL.md")),"beacon-refresh":T(U(Q,".agents","skills","beacon-refresh","SKILL.md"))}}}function vQ(Q){let Z=[];for(let z of["beacon-init","beacon-refresh","beacon-db-design"]){let W=U(Q,".claude","skills",z);if(T(W))S(W,{recursive:!0,force:!0}),Z.push(z)}for(let z of["beacon-init","beacon-refresh"]){let W=U(Q,".agents","skills",z);if(T(W))S(W,{recursive:!0,force:!0}),Z.push(`codex:${z}`)}let $=!1,J=U(Q,".mcp.json");try{let z=JSON.parse(N(J,"utf8"));if(z.mcpServers?.beacon){if(delete z.mcpServers.beacon,$=!0,z.mcpServers&&Object.keys(z.mcpServers).length===0)delete z.mcpServers;if(Object.keys(z).length===0)S(J,{force:!0});else H(J,JSON.stringify(z,null,2)+`
-`)}}catch{}let Y=!1,V=U(Q,"AGENTS.md");try{let z=N(V,"utf8"),W=new RegExp(`\\n?${m}[\\s\\S]*?${GQ}\\n?`);if(W.test(z)){let jQ=z.replace(W,`
+`)}function SZ(Q){let Z=X(Q,".mcp.json"),$={};try{$=JSON.parse(G(Z,"utf8"))}catch{}$.mcpServers=$.mcpServers??{};let J=$.mcpServers.beacon;if(J){if(!J.timeout||J.timeout<S)return J.timeout=S,H(Z,JSON.stringify($,null,2)+`
+`),{path:Z,added:!1,updated:!0};return{path:Z,added:!1,updated:!1}}return $.mcpServers.beacon={command:"beacon",args:["mcp"],timeout:S},H(Z,JSON.stringify($,null,2)+`
+`),{path:Z,added:!0,updated:!1}}function hZ(Q){let Z=X(Q,".mcp.json"),$=!1;try{$=!!JSON.parse(G(Z,"utf8")).mcpServers?.beacon}catch{}let J=!1;try{J=G(X(Q,"AGENTS.md"),"utf8").includes(m)}catch{}let Y=!1;try{Y=/@AGENTS\.md/.test(G(X(Q,"CLAUDE.md"),"utf8"))}catch{}return{repo:Q,mcpRegistered:$,agentsMdBlock:J,claudeMdImport:Y,skills:{"beacon-init":T(X(Q,".claude","skills","beacon-init","SKILL.md")),"beacon-refresh":T(X(Q,".claude","skills","beacon-refresh","SKILL.md"))},codexSkills:{"beacon-init":T(X(Q,".agents","skills","beacon-init","SKILL.md")),"beacon-refresh":T(X(Q,".agents","skills","beacon-refresh","SKILL.md"))}}}function NQ(Q){let Z=[];for(let z of["beacon-init","beacon-refresh","beacon-db-design"]){let U=X(Q,".claude","skills",z);if(T(U))h(U,{recursive:!0,force:!0}),Z.push(z)}for(let z of["beacon-init","beacon-refresh"]){let U=X(Q,".agents","skills",z);if(T(U))h(U,{recursive:!0,force:!0}),Z.push(`codex:${z}`)}let $=!1,J=X(Q,".mcp.json");try{let z=JSON.parse(G(J,"utf8"));if(z.mcpServers?.beacon){if(delete z.mcpServers.beacon,$=!0,z.mcpServers&&Object.keys(z.mcpServers).length===0)delete z.mcpServers;if(Object.keys(z).length===0)h(J,{force:!0});else H(J,JSON.stringify(z,null,2)+`
+`)}}catch{}let Y=!1,V=X(Q,"AGENTS.md");try{let z=G(V,"utf8"),U=new RegExp(`\\n?${m}[\\s\\S]*?${vQ}\\n?`);if(U.test(z)){let BQ=z.replace(U,`
 `).replace(/\n{3,}/g,`
 
-`).trimStart();H(V,jQ.endsWith(`
-`)?jQ:`${jQ}
-`),Y=!0}}catch{}let q=!1,X=U(Q,"CLAUDE.md");try{let z=N(X,"utf8"),W=z.replace(/^[ \t]*@AGENTS\.md[ \t]*\n?/m,"");if(W!==z){if(!W.trim())S(X,{force:!0});else H(X,W);q=!0}}catch{}return{skillsRemoved:Z,mcpUnregistered:$,agentsBlockRemoved:Y,claudeImportRemoved:q}}var BQ=`---
+`).trimStart();H(V,BQ.endsWith(`
+`)?BQ:`${BQ}
+`),Y=!0}}catch{}let q=!1,W=X(Q,"CLAUDE.md");try{let z=G(W,"utf8"),U=z.replace(/^[ \t]*@AGENTS\.md[ \t]*\n?/m,"");if(U!==z){if(!U.trim())h(W,{force:!0});else H(W,U);q=!0}}catch{}return{skillsRemoved:Z,mcpUnregistered:$,agentsBlockRemoved:Y,claudeImportRemoved:q}}var PQ=`---
 name: beacon-init
 description: Read this repository and map its architecture, schema, and roadmap into Beacon (the local visual planning panel). Use when the user runs /beacon-init, asks to "set up Beacon for this repo", or asks to initialize/bootstrap Beacon's map of this codebase.
 ---
@@ -63,7 +63,7 @@ beacon init-persist /tmp/beacon-init.json   # or: beacon init-persist < /tmp/bea
 That one command wires the repo (writes \`.mcp.json\` + skills so your NEXT session gets the \`beacon_*\` tools natively, heals the global install), starts the Beacon daemon if it isn't running, registers + provisions this workspace, and POSTs your analysis to the same \`/api/init\` endpoint the MCP tool uses \u2014 so init completes in THIS session. Read the counts it prints and report them.
 
 After the tool (or \`beacon init-persist\`) returns, tell the user the counts (components / roadmap / tables / endpoints) and point them at the running Beacon panel.
-`,NQ=`---
+`,GQ=`---
 name: beacon-refresh
 description: Re-survey the repo and update Beacon's architecture / schema / endpoints map after /beacon-init was already run \u2014 picks up new components, removed ones, schema changes, and new routes. Use when the user runs /beacon-refresh or asks to "refresh", "update", "re-sync", or "bring Beacon up to date" with the current code.
 ---
@@ -158,7 +158,70 @@ If it returns feedback, revise and call it again.
 If \`beacon_present_plan\` isn't available, the panel isn't wired here \u2014 fall back to ExitPlanMode
 with the same \`\`\`beacon block (Claude Code only; Codex has no ExitPlanMode), or tell the user to
 run \`beacon\` in this repo once.
-`,OZ,m="<!-- beacon:workflow:start -->",GQ="<!-- beacon:workflow:end -->",lQ;var p=M(()=>{cQ();OZ=[{name:"beacon-init",body:()=>BQ},{name:"beacon-refresh",body:()=>NQ}];lQ=`${m}
+`,tQ=`---
+name: beacon-explain
+description: Teach the user part of THIS codebase as an interactive visual lesson on Beacon's /learn page \u2014 a concept map + plain-English narrative they can question \u2014 instead of a wall of text. Use when the user says "explain", "teach me", "walk me through", "how does X work", or "help me understand the Y category".
+---
+
+# Explain the codebase visually (/beacon-explain)
+
+When the user wants to UNDERSTAND part of the code (not build something), don't dump prose in the
+terminal and don't open a plan \u2014 plans are for building. Author an interactive **Lesson** and push it
+with the \`beacon_explain\` MCP tool: a curated concept map (boxes + labeled arrows) beside a
+plain-English narrative on Beacon's /learn page. The tool BLOCKS while the user reads, highlights text
+to ask questions, and drops question notes; it returns their questions, you ANSWER and re-push, looping
+until they Save the lesson. There is NO approve/discard \u2014 understanding, not building.
+
+## 1. Load context first \u2014 don't explain blind
+
+Before writing, call \`beacon_context_for_feature\` / \`beacon_map\` and read the relevant files so the
+lesson is accurate. Name real files, functions, tables, and endpoints \u2014 never vague descriptions.
+
+## 2. Write like a great teacher \u2014 the house style (this is the whole point)
+
+Every lesson must read like a patient senior engineer explaining to a sharp newcomer:
+
+- **Plain English, always.** Define any term the first time it appears. No unexplained jargon, no
+  wall of nouns.
+- **Problem-first.** Open each component with the PROBLEM it solves \u2014 a concrete human scenario, the
+  tension that forced the design, then the decision and what it means. (e.g. "When a salesperson
+  confirms an order it must also land in the ERP \u2014 but the ERP can be slow or down, and you do *not*
+  want confirmation to hang. So the sync is *decoupled*: confirming succeeds immediately and the push
+  happens in the background, with retries.")
+- **Concrete step-by-step flow.** Walk the real path as a numbered list. Each step is ONE clear
+  action and names the real identifier in backticks \u2014 file (\`order-placed-sync-erp.ts\`), function
+  (\`syncOrderToErpWorkflow\`), event (\`order.placed\`), column (\`erp_sync_record\`), value
+  (\`requires_human_action\`). Enumerate the cases (success / retryable / rejected / \u2026) with the plain
+  meaning of each.
+- **Anticipate-and-answer "Why X?".** After the flow, add short sections that answer the confusions a
+  reader will actually have ("Why two status columns?", "Why is the ledger append-only?"). ALWAYS
+  explain why the alternative is worse ("claiming success could hide a real failure; claiming hard
+  failure could cause a duplicate order later").
+- **A worked example with real data.** Show the mechanism running on one concrete case \u2014 ideally a
+  small markdown table of state transitions \u2014 and land the insight ("that's 8 rows for one order, and
+  that's the point").
+- **Typographic discipline.** **Bold** the decisions, *italic* the concepts being introduced, and put
+  \`inline code\` around every real identifier \u2014 on /learn, backticked real file paths become clickable
+  to open in the user's editor.
+
+## 3. Map the prose to the board
+
+Every component/flow you NAME in the narrative becomes a \`node\` (title + a one-line \`summary\` for its
+face + a fuller \`detail\` + the real \`files\` it maps to). Every "A does X to B" becomes an \`edge\` with
+a relationship VERB \u2014 one of: imports, calls, persists to, reads from, writes to, routes to, depends
+on, emits, returns, contains, extends \u2014 never a bare line. Keep the resting set small (~4\u20137 nodes);
+push depth into \`detail\`, not the node face. Supply \`steps\` for the guided walkthrough: the first step
+is the overview (empty \`focusIds\`), then teach one node (or a few) per step in order, each with its
+\`focusIds\`.
+
+## 4. Answer in the loop \u2014 don't stop after one round
+
+\`beacon_explain\` returns the user's questions, each tagged \`[q:ID]\`. Answer EACH by calling
+\`beacon_explain\` AGAIN with the SAME lesson plus \`answers: [{ questionId, answer }]\` (keyed by the id).
+Every answer must ADD understanding (rationale, trade-off) \u2014 never just restate the question. Expand
+the narrative or add nodes where it helps. Keep looping until the tool reports the user saved or closed
+the lesson.
+`,kZ,m="<!-- beacon:workflow:start -->",vQ="<!-- beacon:workflow:end -->",lQ;var p=M(()=>{cQ();kZ=[{name:"beacon-init",body:()=>PQ},{name:"beacon-refresh",body:()=>GQ}];lQ=`${m}
 ## Beacon \u2014 feature workflow
 
 This project uses Beacon (a local planning/visualization panel; run \`beacon\` to open it). When you start work on a FEATURE \u2014 whether referenced via an \`@beacon:feature://\u2026\` mention, an \`@beacon:note://\u2026\` note the user wrote in the Notes panel (treat its checkbox \`- [ ]\` todos as subtasks and order features by their dependencies), or just described in chat \u2014 follow these steps in order:
@@ -215,6 +278,10 @@ Beacon extracts it deterministically and **strips the block from the prose** (it
 
 **The board is built ONLY from the block \u2014 prose is NOT parsed.** If your plan describes ANY database models/tables/columns in the prose (e.g. "Model \`legal_precedent.py\` \u2014 natural key (court, \u2026)"), you MUST also put them in the block's \`tables\` array (with \`columns\`), or the /db tab will be empty for that plan. Same for endpoints (\`endpoints\` with \`uses:[{table,access}]\`) and features (\`features\`). A plan that lists five tables in prose but ships a block with only \`features\` renders an empty database board \u2014 exactly the "I described models but the DB tab is empty" failure. Mirror every DB entity you mention into the block.
 
+### 2c. Mark the files you mention \u2014 write repo-relative paths in backticks
+
+When a plan, feature, or architecture-component description mentions a source file, write its **repo-relative path inside backticks** \u2014 \`app/api/plan/route.ts\`, not "the plan route". On the /plan canvas Beacon turns every backticked token that matches a REAL repo file into a clickable mention that opens it in the user's editor; a bare filename matching several files (e.g. \`route.ts\`) opens a pick-one dropdown of the same-named candidates. The match is deterministic against the live code graph, so a path that isn't a real file just stays plain text \u2014 there's no special syntax to learn and no downside to over-marking: always name files by their real path so the reader can jump straight to the code.
+
 ### 3. At the end, register the work \u2014 in ONE call
 
 Call \`beacon_feature({ action: "done" })\` **ONCE** with a \`features\` array \u2014 one entry per feature the plan created \u2014 each with the files you touched and a short markdown description. This flips each one to **Done** \u2014 including its sub-tasks (the cascade completes every PENDING/IN_PROGRESS child; a sub-task you did NOT finish must be set BLOCKED or CANCELLED before registering, so it survives visibly) \u2014 and keeps \`beacon_context_for_feature\` accurate for the next session.
@@ -226,18 +293,18 @@ Register them all in that single batched call. If a plan added five features, th
 If the feature added or materially changed a REAL architectural component (a subsystem \u2014 NOT a file), also pass \`architecture: [{ title, domain, role, \u2026 }]\` so the Architecture map stays accurate. It upserts curated components by title; never list files as components. If you found a bug or something worth investigating in a component's code, add \`bugs: [{ note }]\` to its architecture entry \u2014 it renders as a bug flag on the node (attributed to the agent); identical open flags are not duplicated. Only flag what you actually saw in the code.
 
 Pull raw planning data anytime with \`beacon_entities\` (features / architecture / tables / endpoints).
-${GQ}`});import{existsSync as c,mkdirSync as KQ,readdirSync as SZ,readFileSync as g,rmSync as hZ,writeFileSync as l}from"fs";import{dirname as tQ,join as K}from"path";function dQ(){return!!process.env.CLAUDE_PLUGIN_ROOT}function aQ(Q=process.env.HOME||process.env.USERPROFILE||""){if(!Q)return null;let Z=K(Q,".claude","plugins");if(!c(Z))return null;let $=[Z];for(let J=0;J<3&&$.length;J++){let Y=[];for(let V of $){let q=K(V,".claude-plugin","plugin.json");try{if(c(q)&&JSON.parse(g(q,"utf8")).name==="beacon")return V}catch{}try{for(let X of SZ(V,{withFileTypes:!0}))if(X.isDirectory())Y.push(K(V,X.name))}catch{}}$=Y}return null}function sQ(Q){return aQ(Q)!==null}function uQ(Q){try{return JSON.parse(g(Q,"utf8"))}catch{return{}}}function rQ(Q,Z){KQ(tQ(Q),{recursive:!0}),l(Q,JSON.stringify(Z,null,2)+`
-`)}function t(Q,Z){let $=uQ(Q);$.hooks=$.hooks??{},$.hooks[Z.event]=$.hooks[Z.event]??[];let J=$.hooks[Z.event];if(J.some((V)=>V.matcher===Z.matcher&&V.hooks?.some((q)=>q.command===Z.command)))return!1;return J.push({matcher:Z.matcher,hooks:[{type:"command",command:Z.command}]}),rQ(Q,$),!0}function d(Q,Z){return(uQ(Q).hooks?.[Z.event]??[]).some((Y)=>Y.hooks?.some((V)=>V.command===Z.command))}function a(Q,Z){let $=uQ(Q),J=$.hooks?.[Z.event];if(!J)return!1;let Y=!1,V=J.map((q)=>{let X=q.hooks?.length??0,z=(q.hooks??[]).filter((W)=>W.command!==Z.command);if(z.length!==X)Y=!0;return{...q,hooks:z}}).filter((q)=>(q.hooks??[]).length>0);if(!Y)return!1;if(V.length)$.hooks[Z.event]=V;else delete $.hooks[Z.event];if($.hooks&&Object.keys($.hooks).length===0)delete $.hooks;return rQ(Q,$),!0}function s(Q,Z,$,J){let Y=`${Z}
+${vQ}`});import{existsSync as c,mkdirSync as KQ,readdirSync as mZ,readFileSync as E,rmSync as pZ,writeFileSync as l}from"fs";import{dirname as dQ,join as K}from"path";function aQ(){return!!process.env.CLAUDE_PLUGIN_ROOT}function sQ(Q=process.env.HOME||process.env.USERPROFILE||""){if(!Q)return null;let Z=K(Q,".claude","plugins");if(!c(Z))return null;let $=[Z];for(let J=0;J<3&&$.length;J++){let Y=[];for(let V of $){let q=K(V,".claude-plugin","plugin.json");try{if(c(q)&&JSON.parse(E(q,"utf8")).name==="beacon")return V}catch{}try{for(let W of mZ(V,{withFileTypes:!0}))if(W.isDirectory())Y.push(K(V,W.name))}catch{}}$=Y}return null}function rQ(Q){return sQ(Q)!==null}function uQ(Q){try{return JSON.parse(E(Q,"utf8"))}catch{return{}}}function oQ(Q,Z){KQ(dQ(Q),{recursive:!0}),l(Q,JSON.stringify(Z,null,2)+`
+`)}function t(Q,Z){let $=uQ(Q);$.hooks=$.hooks??{},$.hooks[Z.event]=$.hooks[Z.event]??[];let J=$.hooks[Z.event];if(J.some((V)=>V.matcher===Z.matcher&&V.hooks?.some((q)=>q.command===Z.command)))return!1;return J.push({matcher:Z.matcher,hooks:[{type:"command",command:Z.command}]}),oQ(Q,$),!0}function d(Q,Z){return(uQ(Q).hooks?.[Z.event]??[]).some((Y)=>Y.hooks?.some((V)=>V.command===Z.command))}function a(Q,Z){let $=uQ(Q),J=$.hooks?.[Z.event];if(!J)return!1;let Y=!1,V=J.map((q)=>{let W=q.hooks?.length??0,z=(q.hooks??[]).filter((U)=>U.command!==Z.command);if(z.length!==W)Y=!0;return{...q,hooks:z}}).filter((q)=>(q.hooks??[]).length>0);if(!Y)return!1;if(V.length)$.hooks[Z.event]=V;else delete $.hooks[Z.event];if($.hooks&&Object.keys($.hooks).length===0)delete $.hooks;return oQ(Q,$),!0}function s(Q,Z,$,J){let Y=`${Z}
 ${J.trim()}
-${$}`,V="";try{V=g(Q,"utf8")}catch{}let q=new RegExp(`${Z}[\\s\\S]*?${$}`);V=q.test(V)?V.replace(q,Y):V.trim()?`${V.trim()}
+${$}`,V="";try{V=E(Q,"utf8")}catch{}let q=new RegExp(`${Z}[\\s\\S]*?${$}`);V=q.test(V)?V.replace(q,Y):V.trim()?`${V.trim()}
 
 ${Y}
 `:`${Y}
-`,KQ(tQ(Q),{recursive:!0}),l(Q,V.endsWith(`
+`,KQ(dQ(Q),{recursive:!0}),l(Q,V.endsWith(`
 `)?V:`${V}
-`)}function E(Q,Z){try{return g(Q,"utf8").includes(Z)}catch{return!1}}function r(Q,Z,$){let J="";try{J=g(Q,"utf8")}catch{return!1}let Y=new RegExp(`${Z}[\\s\\S]*?${$}\\n?`);if(!Y.test(J))return!1;let V=J.replace(Y,"").replace(/\n{3,}/g,`
+`)}function D(Q,Z){try{return E(Q,"utf8").includes(Z)}catch{return!1}}function r(Q,Z,$){let J="";try{J=E(Q,"utf8")}catch{return!1}let Y=new RegExp(`${Z}[\\s\\S]*?${$}\\n?`);if(!Y.test(J))return!1;let V=J.replace(Y,"").replace(/\n{3,}/g,`
 
-`).trimStart();return l(Q,V),!0}function o(Q,Z,$){let J=K(Q,Z);KQ(J,{recursive:!0});let Y=K(J,"SKILL.md");return l(Y,$),Y}function I(Q,Z){return c(K(Q,Z,"SKILL.md"))}function i(Q,Z){let $=K(Q,Z);if(!c($))return!1;return hZ($,{recursive:!0,force:!0}),!0}var j,n=`## Beacon (visual planning panel)
+`).trimStart();return l(Q,V),!0}function o(Q,Z,$){let J=K(Q,Z);KQ(J,{recursive:!0});let Y=K(J,"SKILL.md");return l(Y,$),Y}function I(Q,Z){return c(K(Q,Z,"SKILL.md"))}function i(Q,Z){let $=K(Q,Z);if(!c($))return!1;return pZ($,{recursive:!0,force:!0}),!0}var B,n=`## Beacon (visual planning panel)
 
 This machine has Beacon installed \u2014 a local visual planning surface for the terminal-side
 agent. Beacon proposes feature plans (roadmap features + DB schema + endpoints) via MCP,
@@ -251,6 +318,9 @@ the user reviews on a canvas at /plan, and feedback flows back as the next round
 - User asks to "refresh Beacon" / "update the map" / "bring Beacon up to date" \u2192 invoke
   the \`beacon-refresh\` skill. Re-surveys the repo and updates init-derived nodes while
   preserving anything the user added by hand.
+- User asks to "explain" / "teach me" / "walk me through" / "how does X work" \u2192 if the
+  \`beacon_explain\` MCP tool is available, author an interactive Lesson (a concept map +
+  plain-English narrative on /learn the user questions back) via the \`beacon-explain\` skill.
 - Run \`beacon doctor\` to audit what's wired (global hooks, repo's .mcp.json, AGENTS.md block).
 
 **The plan feedback loop**
@@ -258,20 +328,20 @@ the user reviews on a canvas at /plan, and feedback flows back as the next round
 Feedback bundles inline annotations on the markdown PLUS any edits the user made directly
 on the /map and /db boards (added features, attached subtasks, edited columns, new
 endpoints). Treat board edits as the user's revision intent \u2014 re-propose matching them
-verbatim. Do NOT implement until the tool returns approval.`;var CQ=M(()=>{j=["beacon-init","beacon-refresh","beacon-plan"]});import{mkdirSync as mZ,renameSync as pZ,rmSync as cZ,writeFileSync as lZ}from"fs";import{dirname as nZ}from"path";function e(Q,Z){mZ(nZ(Q),{recursive:!0});let $=`${Q}.tmp`;try{lZ($,Z),pZ($,Q)}catch(J){throw cZ($,{force:!0}),J}}function r0(Q,Z,$=!1){e(Q,JSON.stringify(Z,null,$?2:void 0))}var oQ=()=>{};var VZ={};PQ(VZ,{setupCodexAssets:()=>sZ,removeCodexMcp:()=>YZ,removeCodexArtifacts:()=>FQ,hasCodexMcp:()=>wQ,ensureCodexMcp:()=>JZ,codexMcpProblem:()=>aZ,codexDetected:()=>QZ,auditCodex:()=>RQ,CODEX_HOOKS:()=>R});import{readFileSync as JQ}from"fs";import{homedir as tZ}from"os";import{join as b}from"path";function iQ(){return process.env.HOME||process.env.USERPROFILE||tZ()}function QZ(){if(process.env.BEACON_CODEX==="1")return!0;if(process.env.BEACON_CODEX==="0")return!1;if(fQ===void 0)fQ=Bun.which("codex")!==null;return fQ}function A(Q){try{return Bun.TOML.parse(Q)}catch{return null}}function wQ(){try{return Boolean(A(JQ(w(),"utf8"))?.mcp_servers?.beacon)}catch{return!1}}function aZ(){let Q="";try{Q=JQ(w(),"utf8")}catch{return null}let Z=A(Q);if(!Z)return`~/.codex/config.toml does not parse \u2014 ${D}`;if(Z.mcp_servers?.beacon)return null;if(/^\s*mcp_servers\s*=/m.test(Q))return`mcp_servers is an inline table \u2014 ${D}`;return null}function JZ(){let Q="",Z=!1;try{Q=JQ(w(),"utf8"),Z=!0}catch{}if(Z){let V=A(Q);if(!V)return{added:!1,error:`~/.codex/config.toml does not parse \u2014 ${D}`};if(V.mcp_servers?.beacon)return{added:!1};if(/^\s*mcp_servers\s*=/m.test(Q))return{added:!1,error:`mcp_servers is an inline table \u2014 ${D}`}}let $=!Q?"":Q.endsWith(`
+verbatim. Do NOT implement until the tool returns approval.`;var CQ=M(()=>{B=["beacon-init","beacon-refresh","beacon-plan","beacon-explain"]});import{mkdirSync as cZ,renameSync as lZ,rmSync as nZ,writeFileSync as tZ}from"fs";import{dirname as dZ}from"path";function e(Q,Z){cZ(dZ(Q),{recursive:!0});let $=`${Q}.tmp`;try{tZ($,Z),lZ($,Q)}catch(J){throw nZ($,{force:!0}),J}}function i0(Q,Z,$=!1){e(Q,JSON.stringify(Z,null,$?2:void 0))}var iQ=()=>{};var zZ={};jQ(zZ,{setupCodexAssets:()=>oZ,removeCodexMcp:()=>VZ,removeCodexArtifacts:()=>FQ,hasCodexMcp:()=>wQ,ensureCodexMcp:()=>YZ,codexMcpProblem:()=>rZ,codexDetected:()=>ZZ,auditCodex:()=>RQ,CODEX_HOOKS:()=>R});import{readFileSync as JQ}from"fs";import{homedir as aZ}from"os";import{join as A}from"path";function eQ(){return process.env.HOME||process.env.USERPROFILE||aZ()}function ZZ(){if(process.env.BEACON_CODEX==="1")return!0;if(process.env.BEACON_CODEX==="0")return!1;if(fQ===void 0)fQ=Bun.which("codex")!==null;return fQ}function O(Q){try{return Bun.TOML.parse(Q)}catch{return null}}function wQ(){try{return Boolean(O(JQ(w(),"utf8"))?.mcp_servers?.beacon)}catch{return!1}}function rZ(){let Q="";try{Q=JQ(w(),"utf8")}catch{return null}let Z=O(Q);if(!Z)return`~/.codex/config.toml does not parse \u2014 ${b}`;if(Z.mcp_servers?.beacon)return null;if(/^\s*mcp_servers\s*=/m.test(Q))return`mcp_servers is an inline table \u2014 ${b}`;return null}function YZ(){let Q="",Z=!1;try{Q=JQ(w(),"utf8"),Z=!0}catch{}if(Z){let V=O(Q);if(!V)return{added:!1,error:`~/.codex/config.toml does not parse \u2014 ${b}`};if(V.mcp_servers?.beacon)return{added:!1};if(/^\s*mcp_servers\s*=/m.test(Q))return{added:!1,error:`mcp_servers is an inline table \u2014 ${b}`}}let $=!Q?"":Q.endsWith(`
 `)?`
 `:`
 
-`,J=Q+$+dZ;if(A(J)?.mcp_servers?.beacon?.command!=="beacon")return{added:!1,error:`could not safely append [mcp_servers.beacon] \u2014 ${D}`};return e(w(),J),{added:!0}}function YZ(){let Q="";try{Q=JQ(w(),"utf8")}catch{return{removed:!1}}let Z=Q.split(`
-`),$=Z.indexOf(ZZ);if($===-1)return{removed:!1,skipped:wQ()};let J=Z.indexOf($Z,$);if(J===-1)return{removed:!1,skipped:!0};Z.splice($,J-$+1);let Y=Z.join(`
+`,J=Q+$+sZ;if(O(J)?.mcp_servers?.beacon?.command!=="beacon")return{added:!1,error:`could not safely append [mcp_servers.beacon] \u2014 ${b}`};return e(w(),J),{added:!0}}function VZ(){let Q="";try{Q=JQ(w(),"utf8")}catch{return{removed:!1}}let Z=Q.split(`
+`),$=Z.indexOf($Z);if($===-1)return{removed:!1,skipped:wQ()};let J=Z.indexOf(JZ,$);if(J===-1)return{removed:!1,skipped:!0};Z.splice($,J-$+1);let Y=Z.join(`
 `).replace(/\n{3,}/g,`
 
-`).replace(/^\n+/,"");if(A(Y)===null)return{removed:!1,skipped:!0};return e(w(),Y),{removed:!0}}async function sZ(){let{INIT_SKILL:Q,REFRESH_SKILL:Z,PLAN_SKILL:$}=await Promise.resolve().then(() => (p(),xQ)),J={"beacon-init":Q,"beacon-refresh":Z,"beacon-plan":$},Y=[];for(let z of j){if(!I(ZQ(),z))Y.push(z);o(ZQ(),z,J[z])}let V=0;for(let z of R)if(t(TQ(),{event:z.event,matcher:z.matcher,command:z.command}))V++;let q=E(QQ(),$Q);s(QQ(),$Q,eQ,n);let X=JZ();return{skillsAdded:Y,hooksAdded:V,agentsMdBlockTouched:!q,mcp:X}}function RQ(){let Q={};for(let $ of j)Q[$]=I(ZQ(),$);let Z={};for(let $ of R)Z[$.event]=d(TQ(),{event:$.event,command:$.command});return{detected:QZ(),skills:Q,hooks:Z,agentsMdBlock:E(QQ(),$Q),mcp:wQ()}}function FQ(){let Q=[];for(let Y of j)if(i(ZQ(),Y))Q.push(Y);let Z=0;for(let Y of R)if(a(TQ(),{event:Y.event,command:Y.command}))Z++;let $=r(QQ(),$Q,eQ),J=YZ();return{skillsRemoved:Q,hooksRemoved:Z,agentsMdBlockRemoved:$,mcpRemoved:J.removed,mcpSkipped:J.skipped}}var MQ=()=>b(iQ(),".codex"),TQ=()=>b(MQ(),"hooks.json"),w=()=>b(MQ(),"config.toml"),QQ=()=>b(MQ(),"AGENTS.md"),ZQ=()=>b(iQ(),".agents","skills"),$Q="<!-- beacon:global:start -->",eQ="<!-- beacon:global:end -->",R,fQ,ZZ="# beacon:start (managed by Beacon \u2014 `beacon uninstall` removes this block)",$Z="# beacon:end",dZ,D="add it manually: codex mcp add beacon -- beacon mcp";var gQ=M(()=>{CQ();oQ();R=[{event:"PostToolUse",matcher:"apply_patch",command:"beacon hook",description:"Report file edits to Beacon's active feature so the map stays fresh."},{event:"UserPromptSubmit",matcher:"*",command:"beacon prompt",description:"On feature-y prompts in a Beacon-wired repo, remind the agent to run the context\u2192propose\u2192describe loop (no-op otherwise)."},{event:"Stop",matcher:"*",command:"beacon stop-hook",description:"When the agent ends a turn asking for plan approval in prose, nudge it to present the plan on Beacon's /plan canvas."}];dZ=`${ZZ}
+`).replace(/^\n+/,"");if(O(Y)===null)return{removed:!1,skipped:!0};return e(w(),Y),{removed:!0}}async function oZ(){let{INIT_SKILL:Q,REFRESH_SKILL:Z,PLAN_SKILL:$,EXPLAIN_SKILL:J}=await Promise.resolve().then(() => (p(),xQ)),Y={"beacon-init":Q,"beacon-refresh":Z,"beacon-plan":$,"beacon-explain":J},V=[];for(let U of B){if(!I(ZQ(),U))V.push(U);o(ZQ(),U,Y[U])}let q=0;for(let U of R)if(t(TQ(),{event:U.event,matcher:U.matcher,command:U.command}))q++;let W=D(QQ(),$Q);s(QQ(),$Q,QZ,n);let z=YZ();return{skillsAdded:V,hooksAdded:q,agentsMdBlockTouched:!W,mcp:z}}function RQ(){let Q={};for(let $ of B)Q[$]=I(ZQ(),$);let Z={};for(let $ of R)Z[$.event]=d(TQ(),{event:$.event,command:$.command});return{detected:ZZ(),skills:Q,hooks:Z,agentsMdBlock:D(QQ(),$Q),mcp:wQ()}}function FQ(){let Q=[];for(let Y of B)if(i(ZQ(),Y))Q.push(Y);let Z=0;for(let Y of R)if(a(TQ(),{event:Y.event,command:Y.command}))Z++;let $=r(QQ(),$Q,QZ),J=VZ();return{skillsRemoved:Q,hooksRemoved:Z,agentsMdBlockRemoved:$,mcpRemoved:J.removed,mcpSkipped:J.skipped}}var MQ=()=>A(eQ(),".codex"),TQ=()=>A(MQ(),"hooks.json"),w=()=>A(MQ(),"config.toml"),QQ=()=>A(MQ(),"AGENTS.md"),ZQ=()=>A(eQ(),".agents","skills"),$Q="<!-- beacon:global:start -->",QZ="<!-- beacon:global:end -->",R,fQ,$Z="# beacon:start (managed by Beacon \u2014 `beacon uninstall` removes this block)",JZ="# beacon:end",sZ,b="add it manually: codex mcp add beacon -- beacon mcp";var gQ=M(()=>{CQ();iQ();R=[{event:"PostToolUse",matcher:"apply_patch",command:"beacon hook",description:"Report file edits to Beacon's active feature so the map stays fresh."},{event:"UserPromptSubmit",matcher:"*",command:"beacon prompt",description:"On feature-y prompts in a Beacon-wired repo, remind the agent to run the context\u2192propose\u2192describe loop (no-op otherwise)."},{event:"Stop",matcher:"*",command:"beacon stop-hook",description:"When the agent ends a turn asking for plan approval in prose, nudge it to present the plan on Beacon's /plan canvas."}];sZ=`${$Z}
 [mcp_servers.beacon]
 command = "beacon"
 args = ["mcp"]
-${$Z}
-`});var HZ={};PQ(HZ,{provisionDb:()=>K0});import{createClient as X0}from"@libsql/client";import{drizzle as U0}from"drizzle-orm/libsql";import{migrate as W0}from"drizzle-orm/libsql/migrator";import{readMigrationFiles as H0}from"drizzle-orm/migrator";import{dirname as OQ,join as j0}from"path";import{fileURLToPath as P0}from"url";async function zQ(Q,Z){return(await Q.execute({sql:"SELECT 1 FROM sqlite_master WHERE type='table' AND name = ?",args:[Z]})).rows.length>0}async function v0(Q,Z){let $=await Q.execute(`PRAGMA table_info("${Z}")`);return new Set($.rows.map((J)=>String(J.name)))}async function WZ(Q){if(!await zQ(Q,"__drizzle_migrations"))return 0;let Z=await Q.execute('SELECT count(*) AS n FROM "__drizzle_migrations"');return Number(Z.rows[0]?.n??0)}async function x0(Q){for(let[Z,$]of Object.entries(G0)){if(!await zQ(Q,Z))continue;let J=await v0(Q,Z);for(let Y of $){if(!J.has(Y))continue;await Q.execute(`UPDATE "${Z}" SET "${Y}" = CAST((julianday("${Y}") - 2440587.5) * 86400000 AS INTEGER) WHERE typeof("${Y}") = 'text'`)}}}async function K0(Q,Z=N0){let $=X0({url:Q});try{await $.execute("PRAGMA journal_mode = WAL;"),await $.execute("PRAGMA foreign_keys = ON;"),await $.execute("PRAGMA busy_timeout = 5000;");let J=await zQ($,"__drizzle_migrations"),Y=await zQ($,"Node"),V=!1;if(Y&&!J){let X=H0({migrationsFolder:Z})[0];if(X)await $.execute('CREATE TABLE IF NOT EXISTS "__drizzle_migrations" (id SERIAL PRIMARY KEY, hash text NOT NULL, created_at numeric)'),await $.execute({sql:'INSERT INTO "__drizzle_migrations" ("hash", "created_at") VALUES (?, ?)',args:[X.hash,X.folderMillis]}),V=!0}let q=await WZ($);if(await W0(U0($),{migrationsFolder:Z}),await WZ($)>q)V=!0;return await x0($),{migrated:V}}finally{$.close()}}var B0,N0,G0;var jZ=M(async()=>{B0=OQ(OQ(OQ(P0(import.meta.url)))),N0=process.env.BEACON_MIGRATIONS_DIR||j0(B0,"drizzle"),G0={Node:["createdAt","updatedAt"],Note:["createdAt","updatedAt"],DbTable:["createdAt","updatedAt"],Endpoint:["createdAt","updatedAt"],DraftTable:["createdAt"],SyncState:["codeGraphSyncedAt","updatedAt"],AppSetting:["updatedAt"],ProjectMeta:["updatedAt"],CodeFile:["updatedAt"]}});CQ();import{existsSync as rZ}from"fs";import{homedir as oZ}from"os";import{join as YQ}from"path";function iZ(){return process.env.HOME||process.env.USERPROFILE||oZ()}var VQ=()=>YQ(iZ(),".claude"),EQ=()=>YQ(VQ(),"skills"),IQ=()=>YQ(VQ(),"settings.json"),DQ=()=>YQ(VQ(),"CLAUDE.md"),AQ="<!-- beacon:global:start -->",zZ="<!-- beacon:global:end -->";var eZ=n,O=[{event:"PreToolUse",matcher:"Edit|Write|MultiEdit",command:"beacon guard",description:"Gate edits against the active plan's scope contract (when the scope-guard flag is on): in-scope \u2192 allow, off-scope \u2192 ask the user to authorize. No-op + fail-open otherwise."},{event:"PostToolUse",matcher:"Edit|Write|MultiEdit",command:"beacon hook",description:"Report file edits to Beacon's active feature so the map stays fresh."},{event:"PermissionRequest",matcher:"ExitPlanMode",command:"beacon plan",description:"Pipe the agent's plan markdown into Beacon's /plan canvas for review."},{event:"UserPromptSubmit",matcher:"*",command:"beacon prompt",description:"On feature-y prompts in a Beacon-wired repo, remind the agent to run the context\u2192propose\u2192describe loop (no-op otherwise)."},{event:"Stop",matcher:"*",command:"beacon stop-hook",description:"When the agent ends a turn asking for plan approval in prose (instead of presenting it), nudge it to present the plan on Beacon's /plan canvas. Bounded by stop_hook_active \u2014 at most one nudge."}];function Q0(Q,Z){return o(EQ(),Q,Z)}function qZ(Q){return I(EQ(),Q)}function Z0(Q){return i(EQ(),Q)}function $0(Q){return t(IQ(),Q)}function J0(Q){return d(IQ(),Q)}function Y0(Q){return a(IQ(),Q)}function V0(Q){s(DQ(),AQ,zZ,Q)}function XZ(){return E(DQ(),AQ)}function z0(){return r(DQ(),AQ,zZ)}function UZ(){let Q={};for(let $ of j)Q[$]=qZ($);let Z={};for(let $ of O)Z[$.event]=J0({event:$.event,command:$.command});return{homeExists:rZ(VQ()),skills:Q,hooks:Z,claudeMdBlock:XZ()}}async function q0(){let{INIT_SKILL:Q,REFRESH_SKILL:Z,PLAN_SKILL:$}=await Promise.resolve().then(() => (p(),xQ)),J={"beacon-init":Q,"beacon-refresh":Z,"beacon-plan":$},Y=[];for(let X of j){if(!qZ(X))Y.push(X);Q0(X,J[X])}let V=0;for(let X of O)if($0({event:X.event,matcher:X.matcher,command:X.command}))V++;let q=XZ();return V0(eZ),{skillsAdded:Y,hooksAdded:V,claudeMdBlockTouched:!q}}async function q1(){if(dQ())return{ok:!0,skipped:"plugin",skillsAdded:[],hooksAdded:0,claudeMdBlockTouched:!1};let Q;if(sQ()){try{bQ()}catch{}Q={ok:!0,skipped:"plugin-present",skillsAdded:[],hooksAdded:0,claudeMdBlockTouched:!1}}else try{Q={ok:!0,...await q0()}}catch(Z){Q={ok:!1,error:Z instanceof Error?Z.message:String(Z),skillsAdded:[],hooksAdded:0,claudeMdBlockTouched:!1}}try{let Z=await Promise.resolve().then(() => (gQ(),VZ));if(Z.codexDetected())Q.codex={ok:!0,...await Z.setupCodexAssets()}}catch(Z){Q.codex={ok:!1,error:Z instanceof Error?Z.message:String(Z),skillsAdded:[],hooksAdded:0,agentsMdBlockTouched:!1,mcp:{added:!1}}}return Q}function bQ(){let Q=[];for(let J of j)if(Z0(J))Q.push(J);let Z=0;for(let J of O)if(Y0(J))Z++;let $=z0();return{skillsRemoved:Q,hooksRemoved:Z,claudeMdBlockRemoved:$}}import{AsyncLocalStorage as u0}from"async_hooks";import{spawnSync as C0}from"child_process";import{createHash as f0}from"crypto";import{existsSync as BZ,mkdirSync as y,readFileSync as LQ,writeFileSync as _Q}from"fs";import{homedir as NZ}from"os";import{basename as M0,join as v,parse as T0,resolve as PZ}from"path";function G(){return process.env.BEACON_HOME||v(NZ(),".beacon")}function kQ(){return v(G(),"workspaces.json")}function qQ(Q){return f0("sha256").update(Q).digest("hex").slice(0,12)}function C1(Q=process.cwd()){let Z=C0("git",["rev-parse","--show-toplevel"],{cwd:Q,stdio:["ignore","pipe","ignore"]});if(Z.status===0){let $=Z.stdout?.toString().trim();if($)return $}return Q}function GZ(Q){let Z=PZ(Q);return Z!==PZ(NZ())&&Z!==T0(Z).root}function vZ(){return v(G(),"deleted.json")}function SQ(){try{let Q=JSON.parse(LQ(vZ(),"utf8"));return Array.isArray(Q)?Q:[]}catch{return[]}}function xZ(Q){y(G(),{recursive:!0}),_Q(vZ(),JSON.stringify(Q,null,2))}function KZ(Q){return SQ().includes(Q)}function f1(Q){let Z=SQ();if(!Z.includes(Q))xZ([...Z,Q])}function w0(Q){let Z=SQ();if(Z.includes(Q))xZ(Z.filter(($)=>$!==Q))}function XQ(Q){return v(G(),Q)}function R0(Q){return`file:${v(XQ(Q),"db.sqlite")}`}function L(){try{let Q=JSON.parse(LQ(kQ(),"utf8"));return Array.isArray(Q)?Q:[]}catch{return[]}}function hQ(Q){y(G(),{recursive:!0}),_Q(kQ(),JSON.stringify(Q,null,2))}function UQ(){return L().sort((Q,Z)=>Z.lastOpenedAt.localeCompare(Q.lastOpenedAt))}function u(Q){return L().find((Z)=>Z.id===Q)??null}function uZ(Q,Z,$=new Date().toISOString()){if(!GZ(Q))throw Error(`beacon: refusing to register a non-repo path as a workspace: ${Q}`);let J=qQ(Q);if(KZ(J))throw Error(`beacon: workspace ${J} (${Q}) was deleted \u2014 run \`beacon\` or /beacon-init to re-add it`);let Y=L(),V=Y.find((z)=>z.id===J),q={id:J,path:Q,name:Z||V?.name||M0(Q),lastOpenedAt:$},X=[q,...Y.filter((z)=>z.id!==J)];return y(XQ(J),{recursive:!0}),hQ(X),q}function M1(Q,Z){return w0(qQ(Q)),uZ(Q,Z)}function T1(Q,Z=new Date().toISOString()){let $=L(),J=$.find((Y)=>Y.id===Q);if(!J)return;J.lastOpenedAt=Z,hQ($)}function w1(Q){if(hQ(L().filter((Z)=>Z.id!==Q)),mQ()===Q)F0(UQ()[0]?.id??null)}function CZ(){return v(G(),"active")}function mQ(){try{return LQ(CZ(),"utf8").trim()||null}catch{return null}}function F0(Q){y(G(),{recursive:!0}),_Q(CZ(),Q??"")}function R1(){let Q=mQ();return Q?u(Q):null}function F1(){let Q=I0()??mQ();return Q?u(Q):null}function g1(Q){return u(Q)?.path??null}function E1(){return BZ(kQ())}var fZ="beacon_ws";function MZ(Q,Z){let $=Q.headers.get("cookie");if(!$)return null;for(let J of $.split(";")){let Y=J.indexOf("=");if(Y===-1)continue;if(J.slice(0,Y).trim()===Z)return decodeURIComponent(J.slice(Y+1).trim())}return null}function I1(Q){let Z=Q.headers.get("x-beacon-workspace");if(Z&&u(Z))return Z;let $=MZ(Q,fZ);if($&&u($))return $;return g0()}function g0(){let Q=UQ();return Q.length===1?Q[0].id:null}var E0="x-beacon-workspace-path";async function D1(Q){let Z=Q.headers.get("x-beacon-workspace");if(Z&&u(Z))return Z;let $=Q.headers.get(E0);if($&&GZ($)&&!KZ(qQ($))&&(!Z||qQ($)===Z)){let Y=uZ($);return await D0(Y.id),Y.id}let J=MZ(Q,fZ);if(J&&u(J))return J;return null}var TZ=new u0;function A1(Q,Z){return Q?TZ.run(Q,Z):Z()}function I0(){return TZ.getStore()??null}var yQ=new Set;function b1(Q){yQ.delete(v(XQ(Q),"db.sqlite"))}async function D0(Q){let Z=XQ(Q),$=v(Z,"db.sqlite"),J=BZ($);if(J&&yQ.has($))return{ok:!0,created:!1,migrated:!1};try{y(Z,{recursive:!0});let{provisionDb:Y}=await jZ().then(() => HZ),V=await Y(R0(Q));return yQ.add($),{ok:!0,created:!J,migrated:J&&V.migrated}}catch(Y){return{ok:!1,created:!1,migrated:!1,error:Y instanceof Error?Y.message:String(Y)}}}p();gQ();import{existsSync as WQ,readFileSync as A0,rmSync as b0}from"fs";import{join as O0}from"path";var wZ=process.argv.slice(3),RZ=wZ.includes("--yes")||wZ.includes("-y"),B=(Q)=>`\x1B[32m\u2713\x1B[0m ${Q}`,P=(Q)=>`\x1B[2m${Q}\x1B[0m`,f=(Q)=>`
-\x1B[1m${Q}\x1B[0m`,FZ=(Q)=>`\x1B[33m!\x1B[0m ${Q}`,C=G(),_=UQ(),pQ=UZ();console.log(f(RZ?"Beacon \xB7 uninstall":"Beacon \xB7 uninstall (dry run)"));console.log(f("Global"));console.log(`  ${WQ(C)?`wipe ${C} (${_.length} workspaces)`:`${P(`${C} \u2014 already gone`)}`}`);for(let Q of j)console.log(`  ${pQ.skills[Q]?`remove ~/.claude/skills/${Q}/`:P(`skill ${Q} \u2014 already gone`)}`);for(let Q of O)console.log(`  ${pQ.hooks[Q.event]?`remove hook ${Q.event} \u2192 ${Q.command}`:P(`hook ${Q.event} \u2192 ${Q.command} \u2014 already gone`)}`);console.log(`  ${pQ.claudeMdBlock?"strip Beacon block from ~/.claude/CLAUDE.md":P("global CLAUDE.md block \u2014 already gone")}`);var HQ=RQ();console.log(f("Codex"));for(let Q of j)console.log(`  ${HQ.skills[Q]?`remove ~/.agents/skills/${Q}/`:P(`skill ${Q} \u2014 already gone`)}`);for(let Q of R)console.log(`  ${HQ.hooks[Q.event]?`remove hook ${Q.event} \u2192 ${Q.command} from ~/.codex/hooks.json`:P(`hook ${Q.event} \u2192 ${Q.command} \u2014 already gone`)}`);console.log(`  ${HQ.agentsMdBlock?"strip Beacon block from ~/.codex/AGENTS.md":P("global ~/.codex/AGENTS.md block \u2014 already gone")}`);console.log(`  ${HQ.mcp?"strip [mcp_servers.beacon] from ~/.codex/config.toml (if Beacon wrote it)":P("config.toml beacon entry \u2014 already gone")}`);if(_.length){console.log(f(`Per-repo (${_.length})`));for(let Q of _){if(!WQ(Q.path)){console.log(`  ${P(`${Q.path} \u2014 repo no longer on disk, skipping`)}`);continue}console.log(`  ${Q.path}`),console.log(`     ${P("strip beacon entry from .mcp.json, workflow block from AGENTS.md, skills, CLAUDE.md @-import")}`)}}if(!RZ)console.log(f("Nothing was changed.")),console.log("  Run \x1B[1mbeacon uninstall --yes\x1B[0m to apply."),console.log(`  The \x1B[1mbeacon\x1B[0m binary itself (the cloned source + your PATH symlink) is NOT removed by this \u2014 your install script handles that.
-`),process.exit(0);console.log(f("Applying\u2026"));var F=bQ();if(F.skillsRemoved.length)console.log(`  ${B(`removed skills: ${F.skillsRemoved.join(", ")}`)}`);if(F.hooksRemoved)console.log(`  ${B(`removed ${F.hooksRemoved} hook${F.hooksRemoved===1?"":"s"} from ~/.claude/settings.json`)}`);if(F.claudeMdBlockRemoved)console.log(`  ${B("stripped Beacon block from ~/.claude/CLAUDE.md")}`);var x=FQ();if(x.skillsRemoved.length)console.log(`  ${B(`removed ~/.agents/skills: ${x.skillsRemoved.join(", ")}`)}`);if(x.hooksRemoved)console.log(`  ${B(`removed ${x.hooksRemoved} hook${x.hooksRemoved===1?"":"s"} from ~/.codex/hooks.json`)}`);if(x.agentsMdBlockRemoved)console.log(`  ${B("stripped Beacon block from ~/.codex/AGENTS.md")}`);if(x.mcpRemoved)console.log(`  ${B("stripped [mcp_servers.beacon] from ~/.codex/config.toml")}`);if(x.mcpSkipped)console.log(`  ${FZ("left [mcp_servers.beacon] in ~/.codex/config.toml \u2014 it wasn't written by Beacon (remove with: codex mcp remove beacon)")}`);for(let Q of _){if(!WQ(Q.path))continue;let Z=vQ(Q.path),$=[];if(Z.skillsRemoved.length)$.push(`skills(${Z.skillsRemoved.length})`);if(Z.mcpUnregistered)$.push(".mcp.json");if(Z.agentsBlockRemoved)$.push("AGENTS.md");if(Z.claudeImportRemoved)$.push("CLAUDE.md");if($.length)console.log(`  ${B(`${Q.path} \u2192 ${$.join(", ")}`)}`)}var y0=O0(C,"server.json");try{let{pid:Q}=JSON.parse(A0(y0,"utf8"));if(Q)try{process.kill(Q),console.log(`  ${B(`stopped daemon (pid ${Q})`)}`)}catch{}}catch{}if(WQ(C))b0(C,{recursive:!0,force:!0}),console.log(`  ${B(`removed ${C}`)}`);console.log(f("Done."));console.log(`  ${FZ("The `beacon` binary on your PATH is still there \u2014 run the matching uninstall step from your installer to remove it.")}
+${JZ}
+`});var BZ={};jQ(BZ,{provisionDb:()=>C0});import{createClient as W0}from"@libsql/client";import{drizzle as H0}from"drizzle-orm/libsql";import{migrate as B0}from"drizzle-orm/libsql/migrator";import{readMigrationFiles as j0}from"drizzle-orm/migrator";import{dirname as AQ,join as P0}from"path";import{fileURLToPath as G0}from"url";async function zQ(Q,Z){return(await Q.execute({sql:"SELECT 1 FROM sqlite_master WHERE type='table' AND name = ?",args:[Z]})).rows.length>0}async function K0(Q,Z){let $=await Q.execute(`PRAGMA table_info("${Z}")`);return new Set($.rows.map((J)=>String(J.name)))}async function HZ(Q){if(!await zQ(Q,"__drizzle_migrations"))return 0;let Z=await Q.execute('SELECT count(*) AS n FROM "__drizzle_migrations"');return Number(Z.rows[0]?.n??0)}async function u0(Q){for(let[Z,$]of Object.entries(x0)){if(!await zQ(Q,Z))continue;let J=await K0(Q,Z);for(let Y of $){if(!J.has(Y))continue;await Q.execute(`UPDATE "${Z}" SET "${Y}" = CAST((julianday("${Y}") - 2440587.5) * 86400000 AS INTEGER) WHERE typeof("${Y}") = 'text'`)}}}async function C0(Q,Z=N0){let $=W0({url:Q});try{await $.execute("PRAGMA journal_mode = WAL;"),await $.execute("PRAGMA foreign_keys = ON;"),await $.execute("PRAGMA busy_timeout = 5000;");let J=await zQ($,"__drizzle_migrations"),Y=await zQ($,"Node"),V=!1;if(Y&&!J){let W=j0({migrationsFolder:Z})[0];if(W)await $.execute('CREATE TABLE IF NOT EXISTS "__drizzle_migrations" (id SERIAL PRIMARY KEY, hash text NOT NULL, created_at numeric)'),await $.execute({sql:'INSERT INTO "__drizzle_migrations" ("hash", "created_at") VALUES (?, ?)',args:[W.hash,W.folderMillis]}),V=!0}let q=await HZ($);if(await B0(H0($),{migrationsFolder:Z}),await HZ($)>q)V=!0;return await u0($),{migrated:V}}finally{$.close()}}var v0,N0,x0;var jZ=M(async()=>{v0=AQ(AQ(AQ(G0(import.meta.url)))),N0=process.env.BEACON_MIGRATIONS_DIR||P0(v0,"drizzle"),x0={Node:["createdAt","updatedAt"],Note:["createdAt","updatedAt"],DbTable:["createdAt","updatedAt"],Endpoint:["createdAt","updatedAt"],DraftTable:["createdAt"],SyncState:["codeGraphSyncedAt","updatedAt"],AppSetting:["updatedAt"],ProjectMeta:["updatedAt"],CodeFile:["updatedAt"]}});CQ();import{existsSync as iZ}from"fs";import{homedir as eZ}from"os";import{join as YQ}from"path";function Q0(){return process.env.HOME||process.env.USERPROFILE||eZ()}var VQ=()=>YQ(Q0(),".claude"),EQ=()=>YQ(VQ(),"skills"),DQ=()=>YQ(VQ(),"settings.json"),IQ=()=>YQ(VQ(),"CLAUDE.md"),bQ="<!-- beacon:global:start -->",qZ="<!-- beacon:global:end -->";var Z0=n,y=[{event:"PreToolUse",matcher:"Edit|Write|MultiEdit",command:"beacon guard",description:"Gate edits against the active plan's scope contract (when the scope-guard flag is on): in-scope \u2192 allow, off-scope \u2192 ask the user to authorize. No-op + fail-open otherwise."},{event:"PostToolUse",matcher:"Edit|Write|MultiEdit",command:"beacon hook",description:"Report file edits to Beacon's active feature so the map stays fresh."},{event:"PermissionRequest",matcher:"ExitPlanMode",command:"beacon plan",description:"Pipe the agent's plan markdown into Beacon's /plan canvas for review."},{event:"UserPromptSubmit",matcher:"*",command:"beacon prompt",description:"On feature-y prompts in a Beacon-wired repo, remind the agent to run the context\u2192propose\u2192describe loop (no-op otherwise)."},{event:"Stop",matcher:"*",command:"beacon stop-hook",description:"When the agent ends a turn asking for plan approval in prose (instead of presenting it), nudge it to present the plan on Beacon's /plan canvas. Bounded by stop_hook_active \u2014 at most one nudge."}];function $0(Q,Z){return o(EQ(),Q,Z)}function XZ(Q){return I(EQ(),Q)}function J0(Q){return i(EQ(),Q)}function Y0(Q){return t(DQ(),Q)}function V0(Q){return d(DQ(),Q)}function z0(Q){return a(DQ(),Q)}function q0(Q){s(IQ(),bQ,qZ,Q)}function UZ(){return D(IQ(),bQ)}function X0(){return r(IQ(),bQ,qZ)}function WZ(){let Q={};for(let $ of B)Q[$]=XZ($);let Z={};for(let $ of y)Z[$.event]=V0({event:$.event,command:$.command});return{homeExists:iZ(VQ()),skills:Q,hooks:Z,claudeMdBlock:UZ()}}async function U0(){let{INIT_SKILL:Q,REFRESH_SKILL:Z,PLAN_SKILL:$,EXPLAIN_SKILL:J}=await Promise.resolve().then(() => (p(),xQ)),Y={"beacon-init":Q,"beacon-refresh":Z,"beacon-plan":$,"beacon-explain":J},V=[];for(let z of B){if(!XZ(z))V.push(z);$0(z,Y[z])}let q=0;for(let z of y)if(Y0({event:z.event,matcher:z.matcher,command:z.command}))q++;let W=UZ();return q0(Z0),{skillsAdded:V,hooksAdded:q,claudeMdBlockTouched:!W}}async function U1(){if(aQ())return{ok:!0,skipped:"plugin",skillsAdded:[],hooksAdded:0,claudeMdBlockTouched:!1};let Q;if(rQ()){try{OQ()}catch{}Q={ok:!0,skipped:"plugin-present",skillsAdded:[],hooksAdded:0,claudeMdBlockTouched:!1}}else try{Q={ok:!0,...await U0()}}catch(Z){Q={ok:!1,error:Z instanceof Error?Z.message:String(Z),skillsAdded:[],hooksAdded:0,claudeMdBlockTouched:!1}}try{let Z=await Promise.resolve().then(() => (gQ(),zZ));if(Z.codexDetected())Q.codex={ok:!0,...await Z.setupCodexAssets()}}catch(Z){Q.codex={ok:!1,error:Z instanceof Error?Z.message:String(Z),skillsAdded:[],hooksAdded:0,agentsMdBlockTouched:!1,mcp:{added:!1}}}return Q}function OQ(){let Q=[];for(let J of B)if(J0(J))Q.push(J);let Z=0;for(let J of y)if(z0(J))Z++;let $=X0();return{skillsRemoved:Q,hooksRemoved:Z,claudeMdBlockRemoved:$}}import{AsyncLocalStorage as f0}from"async_hooks";import{spawnSync as M0}from"child_process";import{createHash as T0}from"crypto";import{existsSync as GZ,mkdirSync as k,readFileSync as kQ,writeFileSync as LQ}from"fs";import{homedir as vZ}from"os";import{basename as w0,join as N,parse as R0,resolve as PZ}from"path";function v(){return process.env.BEACON_HOME||N(vZ(),".beacon")}function _Q(){return N(v(),"workspaces.json")}function qQ(Q){return T0("sha256").update(Q).digest("hex").slice(0,12)}function M1(Q=process.cwd()){let Z=M0("git",["rev-parse","--show-toplevel"],{cwd:Q,stdio:["ignore","pipe","ignore"]});if(Z.status===0){let $=Z.stdout?.toString().trim();if($)return $}return Q}function NZ(Q){let Z=PZ(Q);return Z!==PZ(vZ())&&Z!==R0(Z).root}function xZ(){return N(v(),"deleted.json")}function SQ(){try{let Q=JSON.parse(kQ(xZ(),"utf8"));return Array.isArray(Q)?Q:[]}catch{return[]}}function KZ(Q){k(v(),{recursive:!0}),LQ(xZ(),JSON.stringify(Q,null,2))}function uZ(Q){return SQ().includes(Q)}function T1(Q){let Z=SQ();if(!Z.includes(Q))KZ([...Z,Q])}function F0(Q){let Z=SQ();if(Z.includes(Q))KZ(Z.filter(($)=>$!==Q))}function XQ(Q){return N(v(),Q)}function g0(Q){return`file:${N(XQ(Q),"db.sqlite")}`}function L(){try{let Q=JSON.parse(kQ(_Q(),"utf8"));return Array.isArray(Q)?Q:[]}catch{return[]}}function hQ(Q){k(v(),{recursive:!0}),LQ(_Q(),JSON.stringify(Q,null,2))}function UQ(){return L().sort((Q,Z)=>Z.lastOpenedAt.localeCompare(Q.lastOpenedAt))}function u(Q){return L().find((Z)=>Z.id===Q)??null}function CZ(Q,Z,$=new Date().toISOString()){if(!NZ(Q))throw Error(`beacon: refusing to register a non-repo path as a workspace: ${Q}`);let J=qQ(Q);if(uZ(J))throw Error(`beacon: workspace ${J} (${Q}) was deleted \u2014 run \`beacon\` or /beacon-init to re-add it`);let Y=L(),V=Y.find((z)=>z.id===J),q={id:J,path:Q,name:Z||V?.name||w0(Q),lastOpenedAt:$},W=[q,...Y.filter((z)=>z.id!==J)];return k(XQ(J),{recursive:!0}),hQ(W),q}function w1(Q,Z){return F0(qQ(Q)),CZ(Q,Z)}function R1(Q,Z=new Date().toISOString()){let $=L(),J=$.find((Y)=>Y.id===Q);if(!J)return;J.lastOpenedAt=Z,hQ($)}function F1(Q){if(hQ(L().filter((Z)=>Z.id!==Q)),mQ()===Q)E0(UQ()[0]?.id??null)}function fZ(){return N(v(),"active")}function mQ(){try{return kQ(fZ(),"utf8").trim()||null}catch{return null}}function E0(Q){k(v(),{recursive:!0}),LQ(fZ(),Q??"")}function g1(){let Q=mQ();return Q?u(Q):null}function E1(){let Q=b0()??mQ();return Q?u(Q):null}function D1(Q){return u(Q)?.path??null}function I1(){return GZ(_Q())}var MZ="beacon_ws";function TZ(Q,Z){let $=Q.headers.get("cookie");if(!$)return null;for(let J of $.split(";")){let Y=J.indexOf("=");if(Y===-1)continue;if(J.slice(0,Y).trim()===Z)return decodeURIComponent(J.slice(Y+1).trim())}return null}function b1(Q){let Z=Q.headers.get("x-beacon-workspace");if(Z&&u(Z))return Z;let $=TZ(Q,MZ);if($&&u($))return $;return D0()}function D0(){let Q=UQ();return Q.length===1?Q[0].id:null}var I0="x-beacon-workspace-path";async function O1(Q){let Z=Q.headers.get("x-beacon-workspace");if(Z&&u(Z))return Z;let $=Q.headers.get(I0);if($&&NZ($)&&!uZ(qQ($))&&(!Z||qQ($)===Z)){let Y=CZ($);return await O0(Y.id),Y.id}let J=TZ(Q,MZ);if(J&&u(J))return J;return null}var wZ=new f0;function A1(Q,Z){return Q?wZ.run(Q,Z):Z()}function b0(){return wZ.getStore()??null}var yQ=new Set;function y1(Q){yQ.delete(N(XQ(Q),"db.sqlite"))}async function O0(Q){let Z=XQ(Q),$=N(Z,"db.sqlite"),J=GZ($);if(J&&yQ.has($))return{ok:!0,created:!1,migrated:!1};try{k(Z,{recursive:!0});let{provisionDb:Y}=await jZ().then(() => BZ),V=await Y(g0(Q));return yQ.add($),{ok:!0,created:!J,migrated:J&&V.migrated}}catch(Y){return{ok:!1,created:!1,migrated:!1,error:Y instanceof Error?Y.message:String(Y)}}}p();gQ();import{existsSync as WQ,readFileSync as A0,rmSync as y0}from"fs";import{join as k0}from"path";var RZ=process.argv.slice(3),FZ=RZ.includes("--yes")||RZ.includes("-y"),P=(Q)=>`\x1B[32m\u2713\x1B[0m ${Q}`,j=(Q)=>`\x1B[2m${Q}\x1B[0m`,f=(Q)=>`
+\x1B[1m${Q}\x1B[0m`,gZ=(Q)=>`\x1B[33m!\x1B[0m ${Q}`,C=v(),_=UQ(),pQ=WZ();console.log(f(FZ?"Beacon \xB7 uninstall":"Beacon \xB7 uninstall (dry run)"));console.log(f("Global"));console.log(`  ${WQ(C)?`wipe ${C} (${_.length} workspaces)`:`${j(`${C} \u2014 already gone`)}`}`);for(let Q of B)console.log(`  ${pQ.skills[Q]?`remove ~/.claude/skills/${Q}/`:j(`skill ${Q} \u2014 already gone`)}`);for(let Q of y)console.log(`  ${pQ.hooks[Q.event]?`remove hook ${Q.event} \u2192 ${Q.command}`:j(`hook ${Q.event} \u2192 ${Q.command} \u2014 already gone`)}`);console.log(`  ${pQ.claudeMdBlock?"strip Beacon block from ~/.claude/CLAUDE.md":j("global CLAUDE.md block \u2014 already gone")}`);var HQ=RQ();console.log(f("Codex"));for(let Q of B)console.log(`  ${HQ.skills[Q]?`remove ~/.agents/skills/${Q}/`:j(`skill ${Q} \u2014 already gone`)}`);for(let Q of R)console.log(`  ${HQ.hooks[Q.event]?`remove hook ${Q.event} \u2192 ${Q.command} from ~/.codex/hooks.json`:j(`hook ${Q.event} \u2192 ${Q.command} \u2014 already gone`)}`);console.log(`  ${HQ.agentsMdBlock?"strip Beacon block from ~/.codex/AGENTS.md":j("global ~/.codex/AGENTS.md block \u2014 already gone")}`);console.log(`  ${HQ.mcp?"strip [mcp_servers.beacon] from ~/.codex/config.toml (if Beacon wrote it)":j("config.toml beacon entry \u2014 already gone")}`);if(_.length){console.log(f(`Per-repo (${_.length})`));for(let Q of _){if(!WQ(Q.path)){console.log(`  ${j(`${Q.path} \u2014 repo no longer on disk, skipping`)}`);continue}console.log(`  ${Q.path}`),console.log(`     ${j("strip beacon entry from .mcp.json, workflow block from AGENTS.md, skills, CLAUDE.md @-import")}`)}}if(!FZ)console.log(f("Nothing was changed.")),console.log("  Run \x1B[1mbeacon uninstall --yes\x1B[0m to apply."),console.log(`  The \x1B[1mbeacon\x1B[0m binary itself (the cloned source + your PATH symlink) is NOT removed by this \u2014 your install script handles that.
+`),process.exit(0);console.log(f("Applying\u2026"));var F=OQ();if(F.skillsRemoved.length)console.log(`  ${P(`removed skills: ${F.skillsRemoved.join(", ")}`)}`);if(F.hooksRemoved)console.log(`  ${P(`removed ${F.hooksRemoved} hook${F.hooksRemoved===1?"":"s"} from ~/.claude/settings.json`)}`);if(F.claudeMdBlockRemoved)console.log(`  ${P("stripped Beacon block from ~/.claude/CLAUDE.md")}`);var x=FQ();if(x.skillsRemoved.length)console.log(`  ${P(`removed ~/.agents/skills: ${x.skillsRemoved.join(", ")}`)}`);if(x.hooksRemoved)console.log(`  ${P(`removed ${x.hooksRemoved} hook${x.hooksRemoved===1?"":"s"} from ~/.codex/hooks.json`)}`);if(x.agentsMdBlockRemoved)console.log(`  ${P("stripped Beacon block from ~/.codex/AGENTS.md")}`);if(x.mcpRemoved)console.log(`  ${P("stripped [mcp_servers.beacon] from ~/.codex/config.toml")}`);if(x.mcpSkipped)console.log(`  ${gZ("left [mcp_servers.beacon] in ~/.codex/config.toml \u2014 it wasn't written by Beacon (remove with: codex mcp remove beacon)")}`);for(let Q of _){if(!WQ(Q.path))continue;let Z=NQ(Q.path),$=[];if(Z.skillsRemoved.length)$.push(`skills(${Z.skillsRemoved.length})`);if(Z.mcpUnregistered)$.push(".mcp.json");if(Z.agentsBlockRemoved)$.push("AGENTS.md");if(Z.claudeImportRemoved)$.push("CLAUDE.md");if($.length)console.log(`  ${P(`${Q.path} \u2192 ${$.join(", ")}`)}`)}var L0=k0(C,"server.json");try{let{pid:Q}=JSON.parse(A0(L0,"utf8"));if(Q)try{process.kill(Q),console.log(`  ${P(`stopped daemon (pid ${Q})`)}`)}catch{}}catch{}if(WQ(C))y0(C,{recursive:!0,force:!0}),console.log(`  ${P(`removed ${C}`)}`);console.log(f("Done."));console.log(`  ${gZ("The `beacon` binary on your PATH is still there \u2014 run the matching uninstall step from your installer to remove it.")}
 `);

package/dist/lib/assets.js

@@ -1,21 +1,21 @@
 // @bun
-var u=Object.defineProperty;var W=(z)=>z;function E(z,J){this[z]=W.bind(null,J)}var M=(z,J)=>{for(var q in J)u(z,q,{get:J[q],enumerable:!0,configurable:!0,set:E.bind(J,q)})};var A=(z,J)=>()=>(z&&(J=z(z=0)),J);var S=1500,s=480000,a=1800000,B=3600000,d=3000;var I=()=>{};var m={};M(m,{removeRepoAssets:()=>R,installRefreshSkill:()=>j,installPlanSkill:()=>L,installInitSkill:()=>K,installCodexRepoSkills:()=>g,ensureWorkflowDoc:()=>F,ensureMcp:()=>_,auditRepo:()=>h,REFRESH_SKILL:()=>P,PLAN_SKILL:()=>f,INIT_SKILL:()=>k});import{existsSync as D,mkdirSync as U,readFileSync as X,rmSync as C,writeFileSync as G}from"fs";import{join as Q}from"path";function K(z){let J=Q(z,".claude","skills","beacon-init");U(J,{recursive:!0});let q=Q(J,"SKILL.md");return G(q,k),q}function j(z){let J=Q(z,".claude","skills","beacon-refresh");U(J,{recursive:!0});let q=Q(J,"SKILL.md");return G(q,P),q}function L(z){let J=Q(z,".claude","skills","beacon-plan");U(J,{recursive:!0});let q=Q(J,"SKILL.md");return G(q,f),q}function g(z){let J=[];for(let q of O){let Y=Q(z,".agents","skills",q.name);U(Y,{recursive:!0});let $=Q(Y,"SKILL.md");G($,q.body()),J.push($)}return J}function F(z){let J=Q(z,"AGENTS.md"),q="";try{q=X(J,"utf8")}catch{}let Y=new RegExp(`${v}[\\s\\S]*?${b}`);q=Y.test(q)?q.replace(Y,T):`${q.trim()}
+var I=Object.defineProperty;var E=(z)=>z;function M(z,J){this[z]=E.bind(null,J)}var K=(z,J)=>{for(var q in J)I(z,q,{get:J[q],enumerable:!0,configurable:!0,set:M.bind(J,q)})};var T=(z,J)=>()=>(z&&(J=z(z=0)),J);var a=1500,d=480000,p=1800000,C=3600000,c=3000;var f=()=>{};var y={};K(y,{removeRepoAssets:()=>l,installRefreshSkill:()=>O,installPlanSkill:()=>L,installInitSkill:()=>j,installExplainSkill:()=>g,installCodexRepoSkills:()=>_,ensureWorkflowDoc:()=>h,ensureMcp:()=>R,auditRepo:()=>m,REFRESH_SKILL:()=>b,PLAN_SKILL:()=>A,INIT_SKILL:()=>k,EXPLAIN_SKILL:()=>W});import{existsSync as D,mkdirSync as B,readFileSync as H,rmSync as U,writeFileSync as $}from"fs";import{join as Q}from"path";function j(z){let J=Q(z,".claude","skills","beacon-init");B(J,{recursive:!0});let q=Q(J,"SKILL.md");return $(q,k),q}function O(z){let J=Q(z,".claude","skills","beacon-refresh");B(J,{recursive:!0});let q=Q(J,"SKILL.md");return $(q,b),q}function L(z){let J=Q(z,".claude","skills","beacon-plan");B(J,{recursive:!0});let q=Q(J,"SKILL.md");return $(q,A),q}function g(z){let J=Q(z,".claude","skills","beacon-explain");B(J,{recursive:!0});let q=Q(J,"SKILL.md");return $(q,W),q}function _(z){let J=[];for(let q of F){let Y=Q(z,".agents","skills",q.name);B(Y,{recursive:!0});let G=Q(Y,"SKILL.md");$(G,q.body()),J.push(G)}return J}function h(z){let J=Q(z,"AGENTS.md"),q="";try{q=H(J,"utf8")}catch{}let Y=new RegExp(`${v}[\\s\\S]*?${P}`);q=Y.test(q)?q.replace(Y,u):`${q.trim()}
 
-${T}
-`.trimStart(),G(J,q.endsWith(`
+${u}
+`.trimStart(),$(J,q.endsWith(`
 `)?q:`${q}
-`);let $=Q(z,"CLAUDE.md"),H="";try{H=X($,"utf8")}catch{}if(!/@AGENTS\.md/.test(H))G($,`${H?`${H.trim()}
+`);let G=Q(z,"CLAUDE.md"),X="";try{X=H(G,"utf8")}catch{}if(!/@AGENTS\.md/.test(X))$(G,`${X?`${X.trim()}
 
 `:""}@AGENTS.md
-`)}function _(z){let J=Q(z,".mcp.json"),q={};try{q=JSON.parse(X(J,"utf8"))}catch{}q.mcpServers=q.mcpServers??{};let Y=q.mcpServers.beacon;if(Y){if(!Y.timeout||Y.timeout<B)return Y.timeout=B,G(J,JSON.stringify(q,null,2)+`
-`),{path:J,added:!1,updated:!0};return{path:J,added:!1,updated:!1}}return q.mcpServers.beacon={command:"beacon",args:["mcp"],timeout:B},G(J,JSON.stringify(q,null,2)+`
-`),{path:J,added:!0,updated:!1}}function h(z){let J=Q(z,".mcp.json"),q=!1;try{q=!!JSON.parse(X(J,"utf8")).mcpServers?.beacon}catch{}let Y=!1;try{Y=X(Q(z,"AGENTS.md"),"utf8").includes(v)}catch{}let $=!1;try{$=/@AGENTS\.md/.test(X(Q(z,"CLAUDE.md"),"utf8"))}catch{}return{repo:z,mcpRegistered:q,agentsMdBlock:Y,claudeMdImport:$,skills:{"beacon-init":D(Q(z,".claude","skills","beacon-init","SKILL.md")),"beacon-refresh":D(Q(z,".claude","skills","beacon-refresh","SKILL.md"))},codexSkills:{"beacon-init":D(Q(z,".agents","skills","beacon-init","SKILL.md")),"beacon-refresh":D(Q(z,".agents","skills","beacon-refresh","SKILL.md"))}}}function R(z){let J=[];for(let V of["beacon-init","beacon-refresh","beacon-db-design"]){let Z=Q(z,".claude","skills",V);if(D(Z))C(Z,{recursive:!0,force:!0}),J.push(V)}for(let V of["beacon-init","beacon-refresh"]){let Z=Q(z,".agents","skills",V);if(D(Z))C(Z,{recursive:!0,force:!0}),J.push(`codex:${V}`)}let q=!1,Y=Q(z,".mcp.json");try{let V=JSON.parse(X(Y,"utf8"));if(V.mcpServers?.beacon){if(delete V.mcpServers.beacon,q=!0,V.mcpServers&&Object.keys(V.mcpServers).length===0)delete V.mcpServers;if(Object.keys(V).length===0)C(Y,{force:!0});else G(Y,JSON.stringify(V,null,2)+`
-`)}}catch{}let $=!1,H=Q(z,"AGENTS.md");try{let V=X(H,"utf8"),Z=new RegExp(`\\n?${v}[\\s\\S]*?${b}\\n?`);if(Z.test(V)){let N=V.replace(Z,`
+`)}function R(z){let J=Q(z,".mcp.json"),q={};try{q=JSON.parse(H(J,"utf8"))}catch{}q.mcpServers=q.mcpServers??{};let Y=q.mcpServers.beacon;if(Y){if(!Y.timeout||Y.timeout<C)return Y.timeout=C,$(J,JSON.stringify(q,null,2)+`
+`),{path:J,added:!1,updated:!0};return{path:J,added:!1,updated:!1}}return q.mcpServers.beacon={command:"beacon",args:["mcp"],timeout:C},$(J,JSON.stringify(q,null,2)+`
+`),{path:J,added:!0,updated:!1}}function m(z){let J=Q(z,".mcp.json"),q=!1;try{q=!!JSON.parse(H(J,"utf8")).mcpServers?.beacon}catch{}let Y=!1;try{Y=H(Q(z,"AGENTS.md"),"utf8").includes(v)}catch{}let G=!1;try{G=/@AGENTS\.md/.test(H(Q(z,"CLAUDE.md"),"utf8"))}catch{}return{repo:z,mcpRegistered:q,agentsMdBlock:Y,claudeMdImport:G,skills:{"beacon-init":D(Q(z,".claude","skills","beacon-init","SKILL.md")),"beacon-refresh":D(Q(z,".claude","skills","beacon-refresh","SKILL.md"))},codexSkills:{"beacon-init":D(Q(z,".agents","skills","beacon-init","SKILL.md")),"beacon-refresh":D(Q(z,".agents","skills","beacon-refresh","SKILL.md"))}}}function l(z){let J=[];for(let V of["beacon-init","beacon-refresh","beacon-db-design"]){let Z=Q(z,".claude","skills",V);if(D(Z))U(Z,{recursive:!0,force:!0}),J.push(V)}for(let V of["beacon-init","beacon-refresh"]){let Z=Q(z,".agents","skills",V);if(D(Z))U(Z,{recursive:!0,force:!0}),J.push(`codex:${V}`)}let q=!1,Y=Q(z,".mcp.json");try{let V=JSON.parse(H(Y,"utf8"));if(V.mcpServers?.beacon){if(delete V.mcpServers.beacon,q=!0,V.mcpServers&&Object.keys(V.mcpServers).length===0)delete V.mcpServers;if(Object.keys(V).length===0)U(Y,{force:!0});else $(Y,JSON.stringify(V,null,2)+`
+`)}}catch{}let G=!1,X=Q(z,"AGENTS.md");try{let V=H(X,"utf8"),Z=new RegExp(`\\n?${v}[\\s\\S]*?${P}\\n?`);if(Z.test(V)){let N=V.replace(Z,`
 `).replace(/\n{3,}/g,`
 
-`).trimStart();G(H,N.endsWith(`
+`).trimStart();$(X,N.endsWith(`
 `)?N:`${N}
-`),$=!0}}catch{}let w=!1,x=Q(z,"CLAUDE.md");try{let V=X(x,"utf8"),Z=V.replace(/^[ \t]*@AGENTS\.md[ \t]*\n?/m,"");if(Z!==V){if(!Z.trim())C(x,{force:!0});else G(x,Z);w=!0}}catch{}return{skillsRemoved:J,mcpUnregistered:q,agentsBlockRemoved:$,claudeImportRemoved:w}}var k=`---
+`),G=!0}}catch{}let w=!1,x=Q(z,"CLAUDE.md");try{let V=H(x,"utf8"),Z=V.replace(/^[ \t]*@AGENTS\.md[ \t]*\n?/m,"");if(Z!==V){if(!Z.trim())U(x,{force:!0});else $(x,Z);w=!0}}catch{}return{skillsRemoved:J,mcpUnregistered:q,agentsBlockRemoved:G,claudeImportRemoved:w}}var k=`---
 name: beacon-init
 description: Read this repository and map its architecture, schema, and roadmap into Beacon (the local visual planning panel). Use when the user runs /beacon-init, asks to "set up Beacon for this repo", or asks to initialize/bootstrap Beacon's map of this codebase.
 ---
@@ -62,7 +62,7 @@ beacon init-persist /tmp/beacon-init.json   # or: beacon init-persist < /tmp/bea
 That one command wires the repo (writes \`.mcp.json\` + skills so your NEXT session gets the \`beacon_*\` tools natively, heals the global install), starts the Beacon daemon if it isn't running, registers + provisions this workspace, and POSTs your analysis to the same \`/api/init\` endpoint the MCP tool uses \u2014 so init completes in THIS session. Read the counts it prints and report them.
 
 After the tool (or \`beacon init-persist\`) returns, tell the user the counts (components / roadmap / tables / endpoints) and point them at the running Beacon panel.
-`,P=`---
+`,b=`---
 name: beacon-refresh
 description: Re-survey the repo and update Beacon's architecture / schema / endpoints map after /beacon-init was already run \u2014 picks up new components, removed ones, schema changes, and new routes. Use when the user runs /beacon-refresh or asks to "refresh", "update", "re-sync", or "bring Beacon up to date" with the current code.
 ---
@@ -109,7 +109,7 @@ The one caveat: if the user manually edited an INIT-source node on the canvas (e
 If \`beacon_entities\` or \`beacon_init_persist\` isn't available, the Beacon panel isn't running in this repo. Tell the user to run \`beacon\` here first, then re-invoke /beacon-refresh.
 
 After the tool returns, report the final counts plus a one-line summary of the diff you surfaced.
-`,f=`---
+`,A=`---
 name: beacon-plan
 description: Present your current plan or approach to the user on Beacon's /plan canvas for review \u2014 instead of asking for approval in prose. Use when the user says "present the plan", "show me the plan", "let me see it / the plan", or whenever you are about to end a turn asking whether to proceed with a plan, design, or approach.
 ---
@@ -157,7 +157,70 @@ If it returns feedback, revise and call it again.
 If \`beacon_present_plan\` isn't available, the panel isn't wired here \u2014 fall back to ExitPlanMode
 with the same \`\`\`beacon block (Claude Code only; Codex has no ExitPlanMode), or tell the user to
 run \`beacon\` in this repo once.
-`,O,v="<!-- beacon:workflow:start -->",b="<!-- beacon:workflow:end -->",T;var y=A(()=>{I();O=[{name:"beacon-init",body:()=>k},{name:"beacon-refresh",body:()=>P}];T=`${v}
+`,W=`---
+name: beacon-explain
+description: Teach the user part of THIS codebase as an interactive visual lesson on Beacon's /learn page \u2014 a concept map + plain-English narrative they can question \u2014 instead of a wall of text. Use when the user says "explain", "teach me", "walk me through", "how does X work", or "help me understand the Y category".
+---
+
+# Explain the codebase visually (/beacon-explain)
+
+When the user wants to UNDERSTAND part of the code (not build something), don't dump prose in the
+terminal and don't open a plan \u2014 plans are for building. Author an interactive **Lesson** and push it
+with the \`beacon_explain\` MCP tool: a curated concept map (boxes + labeled arrows) beside a
+plain-English narrative on Beacon's /learn page. The tool BLOCKS while the user reads, highlights text
+to ask questions, and drops question notes; it returns their questions, you ANSWER and re-push, looping
+until they Save the lesson. There is NO approve/discard \u2014 understanding, not building.
+
+## 1. Load context first \u2014 don't explain blind
+
+Before writing, call \`beacon_context_for_feature\` / \`beacon_map\` and read the relevant files so the
+lesson is accurate. Name real files, functions, tables, and endpoints \u2014 never vague descriptions.
+
+## 2. Write like a great teacher \u2014 the house style (this is the whole point)
+
+Every lesson must read like a patient senior engineer explaining to a sharp newcomer:
+
+- **Plain English, always.** Define any term the first time it appears. No unexplained jargon, no
+  wall of nouns.
+- **Problem-first.** Open each component with the PROBLEM it solves \u2014 a concrete human scenario, the
+  tension that forced the design, then the decision and what it means. (e.g. "When a salesperson
+  confirms an order it must also land in the ERP \u2014 but the ERP can be slow or down, and you do *not*
+  want confirmation to hang. So the sync is *decoupled*: confirming succeeds immediately and the push
+  happens in the background, with retries.")
+- **Concrete step-by-step flow.** Walk the real path as a numbered list. Each step is ONE clear
+  action and names the real identifier in backticks \u2014 file (\`order-placed-sync-erp.ts\`), function
+  (\`syncOrderToErpWorkflow\`), event (\`order.placed\`), column (\`erp_sync_record\`), value
+  (\`requires_human_action\`). Enumerate the cases (success / retryable / rejected / \u2026) with the plain
+  meaning of each.
+- **Anticipate-and-answer "Why X?".** After the flow, add short sections that answer the confusions a
+  reader will actually have ("Why two status columns?", "Why is the ledger append-only?"). ALWAYS
+  explain why the alternative is worse ("claiming success could hide a real failure; claiming hard
+  failure could cause a duplicate order later").
+- **A worked example with real data.** Show the mechanism running on one concrete case \u2014 ideally a
+  small markdown table of state transitions \u2014 and land the insight ("that's 8 rows for one order, and
+  that's the point").
+- **Typographic discipline.** **Bold** the decisions, *italic* the concepts being introduced, and put
+  \`inline code\` around every real identifier \u2014 on /learn, backticked real file paths become clickable
+  to open in the user's editor.
+
+## 3. Map the prose to the board
+
+Every component/flow you NAME in the narrative becomes a \`node\` (title + a one-line \`summary\` for its
+face + a fuller \`detail\` + the real \`files\` it maps to). Every "A does X to B" becomes an \`edge\` with
+a relationship VERB \u2014 one of: imports, calls, persists to, reads from, writes to, routes to, depends
+on, emits, returns, contains, extends \u2014 never a bare line. Keep the resting set small (~4\u20137 nodes);
+push depth into \`detail\`, not the node face. Supply \`steps\` for the guided walkthrough: the first step
+is the overview (empty \`focusIds\`), then teach one node (or a few) per step in order, each with its
+\`focusIds\`.
+
+## 4. Answer in the loop \u2014 don't stop after one round
+
+\`beacon_explain\` returns the user's questions, each tagged \`[q:ID]\`. Answer EACH by calling
+\`beacon_explain\` AGAIN with the SAME lesson plus \`answers: [{ questionId, answer }]\` (keyed by the id).
+Every answer must ADD understanding (rationale, trade-off) \u2014 never just restate the question. Expand
+the narrative or add nodes where it helps. Keep looping until the tool reports the user saved or closed
+the lesson.
+`,F,v="<!-- beacon:workflow:start -->",P="<!-- beacon:workflow:end -->",u;var S=T(()=>{f();F=[{name:"beacon-init",body:()=>k},{name:"beacon-refresh",body:()=>b}];u=`${v}
 ## Beacon \u2014 feature workflow
 
 This project uses Beacon (a local planning/visualization panel; run \`beacon\` to open it). When you start work on a FEATURE \u2014 whether referenced via an \`@beacon:feature://\u2026\` mention, an \`@beacon:note://\u2026\` note the user wrote in the Notes panel (treat its checkbox \`- [ ]\` todos as subtasks and order features by their dependencies), or just described in chat \u2014 follow these steps in order:
@@ -214,6 +277,10 @@ Beacon extracts it deterministically and **strips the block from the prose** (it
 
 **The board is built ONLY from the block \u2014 prose is NOT parsed.** If your plan describes ANY database models/tables/columns in the prose (e.g. "Model \`legal_precedent.py\` \u2014 natural key (court, \u2026)"), you MUST also put them in the block's \`tables\` array (with \`columns\`), or the /db tab will be empty for that plan. Same for endpoints (\`endpoints\` with \`uses:[{table,access}]\`) and features (\`features\`). A plan that lists five tables in prose but ships a block with only \`features\` renders an empty database board \u2014 exactly the "I described models but the DB tab is empty" failure. Mirror every DB entity you mention into the block.
 
+### 2c. Mark the files you mention \u2014 write repo-relative paths in backticks
+
+When a plan, feature, or architecture-component description mentions a source file, write its **repo-relative path inside backticks** \u2014 \`app/api/plan/route.ts\`, not "the plan route". On the /plan canvas Beacon turns every backticked token that matches a REAL repo file into a clickable mention that opens it in the user's editor; a bare filename matching several files (e.g. \`route.ts\`) opens a pick-one dropdown of the same-named candidates. The match is deterministic against the live code graph, so a path that isn't a real file just stays plain text \u2014 there's no special syntax to learn and no downside to over-marking: always name files by their real path so the reader can jump straight to the code.
+
 ### 3. At the end, register the work \u2014 in ONE call
 
 Call \`beacon_feature({ action: "done" })\` **ONCE** with a \`features\` array \u2014 one entry per feature the plan created \u2014 each with the files you touched and a short markdown description. This flips each one to **Done** \u2014 including its sub-tasks (the cascade completes every PENDING/IN_PROGRESS child; a sub-task you did NOT finish must be set BLOCKED or CANCELLED before registering, so it survives visibly) \u2014 and keeps \`beacon_context_for_feature\` accurate for the next session.
@@ -225,4 +292,4 @@ Register them all in that single batched call. If a plan added five features, th
 If the feature added or materially changed a REAL architectural component (a subsystem \u2014 NOT a file), also pass \`architecture: [{ title, domain, role, \u2026 }]\` so the Architecture map stays accurate. It upserts curated components by title; never list files as components. If you found a bug or something worth investigating in a component's code, add \`bugs: [{ note }]\` to its architecture entry \u2014 it renders as a bug flag on the node (attributed to the agent); identical open flags are not duplicated. Only flag what you actually saw in the code.
 
 Pull raw planning data anytime with \`beacon_entities\` (features / architecture / tables / endpoints).
-${b}`});y();export{R as removeRepoAssets,j as installRefreshSkill,L as installPlanSkill,K as installInitSkill,g as installCodexRepoSkills,F as ensureWorkflowDoc,_ as ensureMcp,h as auditRepo,P as REFRESH_SKILL,f as PLAN_SKILL,k as INIT_SKILL};
+${P}`});S();export{l as removeRepoAssets,O as installRefreshSkill,L as installPlanSkill,j as installInitSkill,g as installExplainSkill,_ as installCodexRepoSkills,h as ensureWorkflowDoc,R as ensureMcp,m as auditRepo,b as REFRESH_SKILL,A as PLAN_SKILL,k as INIT_SKILL,W as EXPLAIN_SKILL};