trybeacon 0.1.65 → 0.1.66

package/dist/lib/codex-install.js

@@ -1,21 +1,21 @@
 // @bun
-var uq=Object.defineProperty;var wq=(q)=>q;function bq(q,z){this[q]=wq.bind(null,z)}var d=(q,z)=>{for(var J in z)uq(q,J,{get:z[J],enumerable:!0,configurable:!0,set:bq.bind(z,J)})};var x=(q,z)=>()=>(q&&(z=q(q=0)),z);var dq=1500,cq=480000,tq=1800000,g=3600000,nq=3000;var c=()=>{};var r={};d(r,{removeRepoAssets:()=>Iq,installRefreshSkill:()=>gq,installPlanSkill:()=>Kq,installInitSkill:()=>jq,installCodexRepoSkills:()=>Nq,ensureWorkflowDoc:()=>Mq,ensureMcp:()=>Rq,auditRepo:()=>fq,REFRESH_SKILL:()=>O,PLAN_SKILL:()=>n,INIT_SKILL:()=>L});import{existsSync as X,mkdirSync as C,readFileSync as B,rmSync as K,writeFileSync as W}from"fs";import{join as $}from"path";function jq(q){let z=$(q,".claude","skills","beacon-init");C(z,{recursive:!0});let J=$(z,"SKILL.md");return W(J,L),J}function gq(q){let z=$(q,".claude","skills","beacon-refresh");C(z,{recursive:!0});let J=$(z,"SKILL.md");return W(J,O),J}function Kq(q){let z=$(q,".claude","skills","beacon-plan");C(z,{recursive:!0});let J=$(z,"SKILL.md");return W(J,n),J}function Nq(q){let z=[];for(let J of Cq){let Q=$(q,".agents","skills",J.name);C(Q,{recursive:!0});let V=$(Q,"SKILL.md");W(V,J.body()),z.push(V)}return z}function Mq(q){let z=$(q,"AGENTS.md"),J="";try{J=B(z,"utf8")}catch{}let Q=new RegExp(`${N}[\\s\\S]*?${y}`);J=Q.test(J)?J.replace(Q,t):`${J.trim()}
+var bq=Object.defineProperty;var wq=(q)=>q;function gq(q,z){this[q]=wq.bind(null,z)}var d=(q,z)=>{for(var J in z)bq(q,J,{get:z[J],enumerable:!0,configurable:!0,set:gq.bind(z,J)})};var x=(q,z)=>()=>(q&&(z=q(q=0)),z);var tq=1500,nq=480000,rq=1800000,C=3600000,oq=3000;var c=()=>{};var o={};d(o,{removeRepoAssets:()=>Aq,installRefreshSkill:()=>Cq,installPlanSkill:()=>Kq,installInitSkill:()=>jq,installExplainSkill:()=>Nq,installCodexRepoSkills:()=>Rq,ensureWorkflowDoc:()=>fq,ensureMcp:()=>Dq,auditRepo:()=>Tq,REFRESH_SKILL:()=>L,PLAN_SKILL:()=>n,INIT_SKILL:()=>O,EXPLAIN_SKILL:()=>r});import{existsSync as G,mkdirSync as u,readFileSync as B,rmSync as K,writeFileSync as H}from"fs";import{join as Z}from"path";function jq(q){let z=Z(q,".claude","skills","beacon-init");u(z,{recursive:!0});let J=Z(z,"SKILL.md");return H(J,O),J}function Cq(q){let z=Z(q,".claude","skills","beacon-refresh");u(z,{recursive:!0});let J=Z(z,"SKILL.md");return H(J,L),J}function Kq(q){let z=Z(q,".claude","skills","beacon-plan");u(z,{recursive:!0});let J=Z(z,"SKILL.md");return H(J,n),J}function Nq(q){let z=Z(q,".claude","skills","beacon-explain");u(z,{recursive:!0});let J=Z(z,"SKILL.md");return H(J,r),J}function Rq(q){let z=[];for(let J of Mq){let Q=Z(q,".agents","skills",J.name);u(Q,{recursive:!0});let V=Z(Q,"SKILL.md");H(V,J.body()),z.push(V)}return z}function fq(q){let z=Z(q,"AGENTS.md"),J="";try{J=B(z,"utf8")}catch{}let Q=new RegExp(`${N}[\\s\\S]*?${y}`);J=Q.test(J)?J.replace(Q,t):`${J.trim()}
 
 ${t}
-`.trimStart(),W(z,J.endsWith(`
+`.trimStart(),H(z,J.endsWith(`
 `)?J:`${J}
-`);let V=$(q,"CLAUDE.md"),Y="";try{Y=B(V,"utf8")}catch{}if(!/@AGENTS\.md/.test(Y))W(V,`${Y?`${Y.trim()}
+`);let V=Z(q,"CLAUDE.md"),Y="";try{Y=B(V,"utf8")}catch{}if(!/@AGENTS\.md/.test(Y))H(V,`${Y?`${Y.trim()}
 
 `:""}@AGENTS.md
-`)}function Rq(q){let z=$(q,".mcp.json"),J={};try{J=JSON.parse(B(z,"utf8"))}catch{}J.mcpServers=J.mcpServers??{};let Q=J.mcpServers.beacon;if(Q){if(!Q.timeout||Q.timeout<g)return Q.timeout=g,W(z,JSON.stringify(J,null,2)+`
-`),{path:z,added:!1,updated:!0};return{path:z,added:!1,updated:!1}}return J.mcpServers.beacon={command:"beacon",args:["mcp"],timeout:g},W(z,JSON.stringify(J,null,2)+`
-`),{path:z,added:!0,updated:!1}}function fq(q){let z=$(q,".mcp.json"),J=!1;try{J=!!JSON.parse(B(z,"utf8")).mcpServers?.beacon}catch{}let Q=!1;try{Q=B($(q,"AGENTS.md"),"utf8").includes(N)}catch{}let V=!1;try{V=/@AGENTS\.md/.test(B($(q,"CLAUDE.md"),"utf8"))}catch{}return{repo:q,mcpRegistered:J,agentsMdBlock:Q,claudeMdImport:V,skills:{"beacon-init":X($(q,".claude","skills","beacon-init","SKILL.md")),"beacon-refresh":X($(q,".claude","skills","beacon-refresh","SKILL.md"))},codexSkills:{"beacon-init":X($(q,".agents","skills","beacon-init","SKILL.md")),"beacon-refresh":X($(q,".agents","skills","beacon-refresh","SKILL.md"))}}}function Iq(q){let z=[];for(let Z of["beacon-init","beacon-refresh","beacon-db-design"]){let P=$(q,".claude","skills",Z);if(X(P))K(P,{recursive:!0,force:!0}),z.push(Z)}for(let Z of["beacon-init","beacon-refresh"]){let P=$(q,".agents","skills",Z);if(X(P))K(P,{recursive:!0,force:!0}),z.push(`codex:${Z}`)}let J=!1,Q=$(q,".mcp.json");try{let Z=JSON.parse(B(Q,"utf8"));if(Z.mcpServers?.beacon){if(delete Z.mcpServers.beacon,J=!0,Z.mcpServers&&Object.keys(Z.mcpServers).length===0)delete Z.mcpServers;if(Object.keys(Z).length===0)K(Q,{force:!0});else W(Q,JSON.stringify(Z,null,2)+`
-`)}}catch{}let V=!1,Y=$(q,"AGENTS.md");try{let Z=B(Y,"utf8"),P=new RegExp(`\\n?${N}[\\s\\S]*?${y}\\n?`);if(P.test(Z)){let E=Z.replace(P,`
+`)}function Dq(q){let z=Z(q,".mcp.json"),J={};try{J=JSON.parse(B(z,"utf8"))}catch{}J.mcpServers=J.mcpServers??{};let Q=J.mcpServers.beacon;if(Q){if(!Q.timeout||Q.timeout<C)return Q.timeout=C,H(z,JSON.stringify(J,null,2)+`
+`),{path:z,added:!1,updated:!0};return{path:z,added:!1,updated:!1}}return J.mcpServers.beacon={command:"beacon",args:["mcp"],timeout:C},H(z,JSON.stringify(J,null,2)+`
+`),{path:z,added:!0,updated:!1}}function Tq(q){let z=Z(q,".mcp.json"),J=!1;try{J=!!JSON.parse(B(z,"utf8")).mcpServers?.beacon}catch{}let Q=!1;try{Q=B(Z(q,"AGENTS.md"),"utf8").includes(N)}catch{}let V=!1;try{V=/@AGENTS\.md/.test(B(Z(q,"CLAUDE.md"),"utf8"))}catch{}return{repo:q,mcpRegistered:J,agentsMdBlock:Q,claudeMdImport:V,skills:{"beacon-init":G(Z(q,".claude","skills","beacon-init","SKILL.md")),"beacon-refresh":G(Z(q,".claude","skills","beacon-refresh","SKILL.md"))},codexSkills:{"beacon-init":G(Z(q,".agents","skills","beacon-init","SKILL.md")),"beacon-refresh":G(Z(q,".agents","skills","beacon-refresh","SKILL.md"))}}}function Aq(q){let z=[];for(let $ of["beacon-init","beacon-refresh","beacon-db-design"]){let U=Z(q,".claude","skills",$);if(G(U))K(U,{recursive:!0,force:!0}),z.push($)}for(let $ of["beacon-init","beacon-refresh"]){let U=Z(q,".agents","skills",$);if(G(U))K(U,{recursive:!0,force:!0}),z.push(`codex:${$}`)}let J=!1,Q=Z(q,".mcp.json");try{let $=JSON.parse(B(Q,"utf8"));if($.mcpServers?.beacon){if(delete $.mcpServers.beacon,J=!0,$.mcpServers&&Object.keys($.mcpServers).length===0)delete $.mcpServers;if(Object.keys($).length===0)K(Q,{force:!0});else H(Q,JSON.stringify($,null,2)+`
+`)}}catch{}let V=!1,Y=Z(q,"AGENTS.md");try{let $=B(Y,"utf8"),U=new RegExp(`\\n?${N}[\\s\\S]*?${y}\\n?`);if(U.test($)){let E=$.replace(U,`
 `).replace(/\n{3,}/g,`
 
-`).trimStart();W(Y,E.endsWith(`
+`).trimStart();H(Y,E.endsWith(`
 `)?E:`${E}
-`),V=!0}}catch{}let U=!1,H=$(q,"CLAUDE.md");try{let Z=B(H,"utf8"),P=Z.replace(/^[ \t]*@AGENTS\.md[ \t]*\n?/m,"");if(P!==Z){if(!P.trim())K(H,{force:!0});else W(H,P);U=!0}}catch{}return{skillsRemoved:z,mcpUnregistered:J,agentsBlockRemoved:V,claudeImportRemoved:U}}var L=`---
+`),V=!0}}catch{}let W=!1,P=Z(q,"CLAUDE.md");try{let $=B(P,"utf8"),U=$.replace(/^[ \t]*@AGENTS\.md[ \t]*\n?/m,"");if(U!==$){if(!U.trim())K(P,{force:!0});else H(P,U);W=!0}}catch{}return{skillsRemoved:z,mcpUnregistered:J,agentsBlockRemoved:V,claudeImportRemoved:W}}var O=`---
 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.
-`,O=`---
+`,L=`---
 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.
 ---
@@ -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.
-`,Cq,N="<!-- beacon:workflow:start -->",y="<!-- beacon:workflow:end -->",t;var o=x(()=>{c();Cq=[{name:"beacon-init",body:()=>L},{name:"beacon-refresh",body:()=>O}];t=`${N}
+`,r=`---
+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.
+`,Mq,N="<!-- beacon:workflow:start -->",y="<!-- beacon:workflow:end -->",t;var i=x(()=>{c();Mq=[{name:"beacon-init",body:()=>O},{name:"beacon-refresh",body:()=>L}];t=`${N}
 ## 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:
@@ -229,18 +292,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).
-${y}`});import{existsSync as M,mkdirSync as h,readdirSync as Aq,readFileSync as u,rmSync as Dq,writeFileSync as R}from"fs";import{dirname as i,join as v}from"path";function Jz(){return!!process.env.CLAUDE_PLUGIN_ROOT}function Tq(q=process.env.HOME||process.env.USERPROFILE||""){if(!q)return null;let z=v(q,".claude","plugins");if(!M(z))return null;let J=[z];for(let Q=0;Q<3&&J.length;Q++){let V=[];for(let Y of J){let U=v(Y,".claude-plugin","plugin.json");try{if(M(U)&&JSON.parse(u(U,"utf8")).name==="beacon")return Y}catch{}try{for(let H of Aq(Y,{withFileTypes:!0}))if(H.isDirectory())V.push(v(Y,H.name))}catch{}}J=V}return null}function Qz(q){return Tq(q)!==null}function _(q){try{return JSON.parse(u(q,"utf8"))}catch{return{}}}function qq(q,z){h(i(q),{recursive:!0}),R(q,JSON.stringify(z,null,2)+`
-`)}function zq(q,z){let J=_(q);J.hooks=J.hooks??{},J.hooks[z.event]=J.hooks[z.event]??[];let Q=J.hooks[z.event];if(Q.some((Y)=>Y.matcher===z.matcher&&Y.hooks?.some((U)=>U.command===z.command)))return!1;return Q.push({matcher:z.matcher,hooks:[{type:"command",command:z.command}]}),qq(q,J),!0}function Jq(q,z){return(_(q).hooks?.[z.event]??[]).some((V)=>V.hooks?.some((Y)=>Y.command===z.command))}function Qq(q,z){let J=_(q),Q=J.hooks?.[z.event];if(!Q)return!1;let V=!1,Y=Q.map((U)=>{let H=U.hooks?.length??0,Z=(U.hooks??[]).filter((P)=>P.command!==z.command);if(Z.length!==H)V=!0;return{...U,hooks:Z}}).filter((U)=>(U.hooks??[]).length>0);if(!V)return!1;if(Y.length)J.hooks[z.event]=Y;else delete J.hooks[z.event];if(J.hooks&&Object.keys(J.hooks).length===0)delete J.hooks;return qq(q,J),!0}function Vq(q,z,J,Q){let V=`${z}
+${y}`});import{existsSync as M,mkdirSync as h,readdirSync as Iq,readFileSync as b,rmSync as kq,writeFileSync as R}from"fs";import{dirname as e,join as v}from"path";function Vz(){return!!process.env.CLAUDE_PLUGIN_ROOT}function Fq(q=process.env.HOME||process.env.USERPROFILE||""){if(!q)return null;let z=v(q,".claude","plugins");if(!M(z))return null;let J=[z];for(let Q=0;Q<3&&J.length;Q++){let V=[];for(let Y of J){let W=v(Y,".claude-plugin","plugin.json");try{if(M(W)&&JSON.parse(b(W,"utf8")).name==="beacon")return Y}catch{}try{for(let P of Iq(Y,{withFileTypes:!0}))if(P.isDirectory())V.push(v(Y,P.name))}catch{}}J=V}return null}function Yz(q){return Fq(q)!==null}function _(q){try{return JSON.parse(b(q,"utf8"))}catch{return{}}}function zq(q,z){h(e(q),{recursive:!0}),R(q,JSON.stringify(z,null,2)+`
+`)}function Jq(q,z){let J=_(q);J.hooks=J.hooks??{},J.hooks[z.event]=J.hooks[z.event]??[];let Q=J.hooks[z.event];if(Q.some((Y)=>Y.matcher===z.matcher&&Y.hooks?.some((W)=>W.command===z.command)))return!1;return Q.push({matcher:z.matcher,hooks:[{type:"command",command:z.command}]}),zq(q,J),!0}function Qq(q,z){return(_(q).hooks?.[z.event]??[]).some((V)=>V.hooks?.some((Y)=>Y.command===z.command))}function Vq(q,z){let J=_(q),Q=J.hooks?.[z.event];if(!Q)return!1;let V=!1,Y=Q.map((W)=>{let P=W.hooks?.length??0,$=(W.hooks??[]).filter((U)=>U.command!==z.command);if($.length!==P)V=!0;return{...W,hooks:$}}).filter((W)=>(W.hooks??[]).length>0);if(!V)return!1;if(Y.length)J.hooks[z.event]=Y;else delete J.hooks[z.event];if(J.hooks&&Object.keys(J.hooks).length===0)delete J.hooks;return zq(q,J),!0}function Yq(q,z,J,Q){let V=`${z}
 ${Q.trim()}
-${J}`,Y="";try{Y=u(q,"utf8")}catch{}let U=new RegExp(`${z}[\\s\\S]*?${J}`);Y=U.test(Y)?Y.replace(U,V):Y.trim()?`${Y.trim()}
+${J}`,Y="";try{Y=b(q,"utf8")}catch{}let W=new RegExp(`${z}[\\s\\S]*?${J}`);Y=W.test(Y)?Y.replace(W,V):Y.trim()?`${Y.trim()}
 
 ${V}
 `:`${V}
-`,h(i(q),{recursive:!0}),R(q,Y.endsWith(`
+`,h(e(q),{recursive:!0}),R(q,Y.endsWith(`
 `)?Y:`${Y}
-`)}function m(q,z){try{return u(q,"utf8").includes(z)}catch{return!1}}function Yq(q,z,J){let Q="";try{Q=u(q,"utf8")}catch{return!1}let V=new RegExp(`${z}[\\s\\S]*?${J}\\n?`);if(!V.test(Q))return!1;let Y=Q.replace(V,"").replace(/\n{3,}/g,`
+`)}function m(q,z){try{return b(q,"utf8").includes(z)}catch{return!1}}function Zq(q,z,J){let Q="";try{Q=b(q,"utf8")}catch{return!1}let V=new RegExp(`${z}[\\s\\S]*?${J}\\n?`);if(!V.test(Q))return!1;let Y=Q.replace(V,"").replace(/\n{3,}/g,`
 
-`).trimStart();return R(q,Y),!0}function Zq(q,z,J){let Q=v(q,z);h(Q,{recursive:!0});let V=v(Q,"SKILL.md");return R(V,J),V}function S(q,z){return M(v(q,z,"SKILL.md"))}function $q(q,z){let J=v(q,z);if(!M(J))return!1;return Dq(J,{recursive:!0,force:!0}),!0}var f,e=`## Beacon (visual planning panel)
+`).trimStart();return R(q,Y),!0}function $q(q,z,J){let Q=v(q,z);h(Q,{recursive:!0});let V=v(Q,"SKILL.md");return R(V,J),V}function S(q,z){return M(v(q,z,"SKILL.md"))}function Uq(q,z){let J=v(q,z);if(!M(J))return!1;return kq(J,{recursive:!0,force:!0}),!0}var f,qq=`## 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,
@@ -254,6 +317,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**
@@ -261,17 +327,17 @@ 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 Uq=x(()=>{f=["beacon-init","beacon-refresh","beacon-plan"]});import{mkdirSync as kq,renameSync as Fq,rmSync as Eq,writeFileSync as Lq}from"fs";import{dirname as Oq}from"path";function I(q,z){kq(Oq(q),{recursive:!0});let J=`${q}.tmp`;try{Lq(J,z),Fq(J,q)}catch(Q){throw Eq(J,{force:!0}),Q}}function $z(q,z,J=!1){I(q,JSON.stringify(z,null,J?2:void 0))}var Pq=()=>{};var aq={};d(aq,{setupCodexAssets:()=>mq,removeCodexMcp:()=>xq,removeCodexArtifacts:()=>pq,hasCodexMcp:()=>s,ensureCodexMcp:()=>Gq,codexMcpProblem:()=>_q,codexDetected:()=>Bq,auditCodex:()=>Sq,CODEX_HOOKS:()=>F});import{readFileSync as k}from"fs";import{homedir as yq}from"os";import{join as j}from"path";function Wq(){return process.env.HOME||process.env.USERPROFILE||yq()}function Bq(){if(process.env.BEACON_CODEX==="1")return!0;if(process.env.BEACON_CODEX==="0")return!1;if(p===void 0)p=Bun.which("codex")!==null;return p}function b(q){try{return Bun.TOML.parse(q)}catch{return null}}function s(){try{return Boolean(b(k(G(),"utf8"))?.mcp_servers?.beacon)}catch{return!1}}function _q(){let q="";try{q=k(G(),"utf8")}catch{return null}let z=b(q);if(!z)return`~/.codex/config.toml does not parse \u2014 ${w}`;if(z.mcp_servers?.beacon)return null;if(/^\s*mcp_servers\s*=/m.test(q))return`mcp_servers is an inline table \u2014 ${w}`;return null}function Gq(){let q="",z=!1;try{q=k(G(),"utf8"),z=!0}catch{}if(z){let Y=b(q);if(!Y)return{added:!1,error:`~/.codex/config.toml does not parse \u2014 ${w}`};if(Y.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 ${w}`}}let J=!q?"":q.endsWith(`
+verbatim. Do NOT implement until the tool returns approval.`;var Wq=x(()=>{f=["beacon-init","beacon-refresh","beacon-plan","beacon-explain"]});import{mkdirSync as Eq,renameSync as Oq,rmSync as Lq,writeFileSync as yq}from"fs";import{dirname as hq}from"path";function D(q,z){Eq(hq(q),{recursive:!0});let J=`${q}.tmp`;try{yq(J,z),Oq(J,q)}catch(Q){throw Lq(J,{force:!0}),Q}}function Wz(q,z,J=!1){D(q,JSON.stringify(z,null,J?2:void 0))}var Hq=()=>{};var sq={};d(sq,{setupCodexAssets:()=>pq,removeCodexMcp:()=>uq,removeCodexArtifacts:()=>lq,hasCodexMcp:()=>s,ensureCodexMcp:()=>xq,codexMcpProblem:()=>Sq,codexDetected:()=>vq,auditCodex:()=>aq,CODEX_HOOKS:()=>F});import{readFileSync as k}from"fs";import{homedir as _q}from"os";import{join as j}from"path";function Pq(){return process.env.HOME||process.env.USERPROFILE||_q()}function vq(){if(process.env.BEACON_CODEX==="1")return!0;if(process.env.BEACON_CODEX==="0")return!1;if(p===void 0)p=Bun.which("codex")!==null;return p}function g(q){try{return Bun.TOML.parse(q)}catch{return null}}function s(){try{return Boolean(g(k(X(),"utf8"))?.mcp_servers?.beacon)}catch{return!1}}function Sq(){let q="";try{q=k(X(),"utf8")}catch{return null}let z=g(q);if(!z)return`~/.codex/config.toml does not parse \u2014 ${w}`;if(z.mcp_servers?.beacon)return null;if(/^\s*mcp_servers\s*=/m.test(q))return`mcp_servers is an inline table \u2014 ${w}`;return null}function xq(){let q="",z=!1;try{q=k(X(),"utf8"),z=!0}catch{}if(z){let Y=g(q);if(!Y)return{added:!1,error:`~/.codex/config.toml does not parse \u2014 ${w}`};if(Y.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 ${w}`}}let J=!q?"":q.endsWith(`
 `)?`
 `:`
 
-`,Q=q+J+hq;if(b(Q)?.mcp_servers?.beacon?.command!=="beacon")return{added:!1,error:`could not safely append [mcp_servers.beacon] \u2014 ${w}`};return I(G(),Q),{added:!0}}function xq(){let q="";try{q=k(G(),"utf8")}catch{return{removed:!1}}let z=q.split(`
-`),J=z.indexOf(vq);if(J===-1)return{removed:!1,skipped:s()};let Q=z.indexOf(Xq,J);if(Q===-1)return{removed:!1,skipped:!0};z.splice(J,Q-J+1);let V=z.join(`
+`,Q=q+J+mq;if(g(Q)?.mcp_servers?.beacon?.command!=="beacon")return{added:!1,error:`could not safely append [mcp_servers.beacon] \u2014 ${w}`};return D(X(),Q),{added:!0}}function uq(){let q="";try{q=k(X(),"utf8")}catch{return{removed:!1}}let z=q.split(`
+`),J=z.indexOf(Gq);if(J===-1)return{removed:!1,skipped:s()};let Q=z.indexOf(Xq,J);if(Q===-1)return{removed:!1,skipped:!0};z.splice(J,Q-J+1);let V=z.join(`
 `).replace(/\n{3,}/g,`
 
-`).replace(/^\n+/,"");if(b(V)===null)return{removed:!1,skipped:!0};return I(G(),V),{removed:!0}}async function mq(){let{INIT_SKILL:q,REFRESH_SKILL:z,PLAN_SKILL:J}=await Promise.resolve().then(() => (o(),r)),Q={"beacon-init":q,"beacon-refresh":z,"beacon-plan":J},V=[];for(let Z of f){if(!S(D(),Z))V.push(Z);Zq(D(),Z,Q[Z])}let Y=0;for(let Z of F)if(zq(l(),{event:Z.event,matcher:Z.matcher,command:Z.command}))Y++;let U=m(A(),T);Vq(A(),T,Hq,e);let H=Gq();return{skillsAdded:V,hooksAdded:Y,agentsMdBlockTouched:!U,mcp:H}}function Sq(){let q={};for(let J of f)q[J]=S(D(),J);let z={};for(let J of F)z[J.event]=Jq(l(),{event:J.event,command:J.command});return{detected:Bq(),skills:q,hooks:z,agentsMdBlock:m(A(),T),mcp:s()}}function pq(){let q=[];for(let V of f)if($q(D(),V))q.push(V);let z=0;for(let V of F)if(Qq(l(),{event:V.event,command:V.command}))z++;let J=Yq(A(),T,Hq),Q=xq();return{skillsRemoved:q,hooksRemoved:z,agentsMdBlockRemoved:J,mcpRemoved:Q.removed,mcpSkipped:Q.skipped}}var a=()=>j(Wq(),".codex"),l=()=>j(a(),"hooks.json"),G=()=>j(a(),"config.toml"),A=()=>j(a(),"AGENTS.md"),D=()=>j(Wq(),".agents","skills"),T="<!-- beacon:global:start -->",Hq="<!-- beacon:global:end -->",F,p,vq="# beacon:start (managed by Beacon \u2014 `beacon uninstall` removes this block)",Xq="# beacon:end",hq,w="add it manually: codex mcp add beacon -- beacon mcp";var lq=x(()=>{Uq();Pq();F=[{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."}];hq=`${vq}
+`).replace(/^\n+/,"");if(g(V)===null)return{removed:!1,skipped:!0};return D(X(),V),{removed:!0}}async function pq(){let{INIT_SKILL:q,REFRESH_SKILL:z,PLAN_SKILL:J,EXPLAIN_SKILL:Q}=await Promise.resolve().then(() => (i(),o)),V={"beacon-init":q,"beacon-refresh":z,"beacon-plan":J,"beacon-explain":Q},Y=[];for(let U of f){if(!S(A(),U))Y.push(U);$q(A(),U,V[U])}let W=0;for(let U of F)if(Jq(l(),{event:U.event,matcher:U.matcher,command:U.command}))W++;let P=m(T(),I);Yq(T(),I,Bq,qq);let $=xq();return{skillsAdded:Y,hooksAdded:W,agentsMdBlockTouched:!P,mcp:$}}function aq(){let q={};for(let J of f)q[J]=S(A(),J);let z={};for(let J of F)z[J.event]=Qq(l(),{event:J.event,command:J.command});return{detected:vq(),skills:q,hooks:z,agentsMdBlock:m(T(),I),mcp:s()}}function lq(){let q=[];for(let V of f)if(Uq(A(),V))q.push(V);let z=0;for(let V of F)if(Vq(l(),{event:V.event,command:V.command}))z++;let J=Zq(T(),I,Bq),Q=uq();return{skillsRemoved:q,hooksRemoved:z,agentsMdBlockRemoved:J,mcpRemoved:Q.removed,mcpSkipped:Q.skipped}}var a=()=>j(Pq(),".codex"),l=()=>j(a(),"hooks.json"),X=()=>j(a(),"config.toml"),T=()=>j(a(),"AGENTS.md"),A=()=>j(Pq(),".agents","skills"),I="<!-- beacon:global:start -->",Bq="<!-- beacon:global:end -->",F,p,Gq="# beacon:start (managed by Beacon \u2014 `beacon uninstall` removes this block)",Xq="# beacon:end",mq,w="add it manually: codex mcp add beacon -- beacon mcp";var dq=x(()=>{Wq();Hq();F=[{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."}];mq=`${Gq}
 [mcp_servers.beacon]
 command = "beacon"
 args = ["mcp"]
 ${Xq}
-`});lq();export{mq as setupCodexAssets,xq as removeCodexMcp,pq as removeCodexArtifacts,s as hasCodexMcp,Gq as ensureCodexMcp,_q as codexMcpProblem,Bq as codexDetected,Sq as auditCodex,F as CODEX_HOOKS};
+`});dq();export{pq as setupCodexAssets,uq as removeCodexMcp,lq as removeCodexArtifacts,s as hasCodexMcp,xq as ensureCodexMcp,Sq as codexMcpProblem,vq as codexDetected,aq as auditCodex,F as CODEX_HOOKS};

package/dist/lib/global-install.js

@@ -1,21 +1,21 @@
 // @bun
-var yq=Object.defineProperty;var Aq=(q)=>q;function Dq(q,z){this[q]=Aq.bind(null,z)}var Xq=(q,z)=>{for(var J in z)yq(q,J,{get:z[J],enumerable:!0,configurable:!0,set:Dq.bind(z,J)})};var B=(q,z)=>()=>(q&&(z=q(q=0)),z);var Bz=1500,gz=480000,Nz=1800000,C=3600000,Gz=3000;var Uq=()=>{};var l={};Xq(l,{removeRepoAssets:()=>cq,installRefreshSkill:()=>kq,installPlanSkill:()=>hq,installInitSkill:()=>Oq,installCodexRepoSkills:()=>_q,ensureWorkflowDoc:()=>pq,ensureMcp:()=>mq,auditRepo:()=>Sq,REFRESH_SKILL:()=>n,PLAN_SKILL:()=>wq,INIT_SKILL:()=>r});import{existsSync as v,mkdirSync as F,readFileSync as H,rmSync as f,writeFileSync as U}from"fs";import{join as $}from"path";function Oq(q){let z=$(q,".claude","skills","beacon-init");F(z,{recursive:!0});let J=$(z,"SKILL.md");return U(J,r),J}function kq(q){let z=$(q,".claude","skills","beacon-refresh");F(z,{recursive:!0});let J=$(z,"SKILL.md");return U(J,n),J}function hq(q){let z=$(q,".claude","skills","beacon-plan");F(z,{recursive:!0});let J=$(z,"SKILL.md");return U(J,wq),J}function _q(q){let z=[];for(let J of Lq){let Q=$(q,".agents","skills",J.name);F(Q,{recursive:!0});let V=$(Q,"SKILL.md");U(V,J.body()),z.push(V)}return z}function pq(q){let z=$(q,"AGENTS.md"),J="";try{J=H(z,"utf8")}catch{}let Q=new RegExp(`${R}[\\s\\S]*?${s}`);J=Q.test(J)?J.replace(Q,Hq):`${J.trim()}
+var Iq=Object.defineProperty;var Aq=(q)=>q;function Oq(q,z){this[q]=Aq.bind(null,z)}var Pq=(q,z)=>{for(var J in z)Iq(q,J,{get:z[J],enumerable:!0,configurable:!0,set:Oq.bind(z,J)})};var B=(q,z)=>()=>(q&&(z=q(q=0)),z);var Gz=1500,Nz=480000,bz=1800000,f=3600000,uz=3000;var Xq=()=>{};var l={};Pq(l,{removeRepoAssets:()=>tq,installRefreshSkill:()=>hq,installPlanSkill:()=>Lq,installInitSkill:()=>kq,installExplainSkill:()=>_q,installCodexRepoSkills:()=>pq,ensureWorkflowDoc:()=>Sq,ensureMcp:()=>cq,auditRepo:()=>aq,REFRESH_SKILL:()=>s,PLAN_SKILL:()=>wq,INIT_SKILL:()=>r,EXPLAIN_SKILL:()=>xq});import{existsSync as v,mkdirSync as g,readFileSync as H,rmSync as F,writeFileSync as X}from"fs";import{join as $}from"path";function kq(q){let z=$(q,".claude","skills","beacon-init");g(z,{recursive:!0});let J=$(z,"SKILL.md");return X(J,r),J}function hq(q){let z=$(q,".claude","skills","beacon-refresh");g(z,{recursive:!0});let J=$(z,"SKILL.md");return X(J,s),J}function Lq(q){let z=$(q,".claude","skills","beacon-plan");g(z,{recursive:!0});let J=$(z,"SKILL.md");return X(J,wq),J}function _q(q){let z=$(q,".claude","skills","beacon-explain");g(z,{recursive:!0});let J=$(z,"SKILL.md");return X(J,xq),J}function pq(q){let z=[];for(let J of mq){let Q=$(q,".agents","skills",J.name);g(Q,{recursive:!0});let V=$(Q,"SKILL.md");X(V,J.body()),z.push(V)}return z}function Sq(q){let z=$(q,"AGENTS.md"),J="";try{J=H(z,"utf8")}catch{}let Q=new RegExp(`${R}[\\s\\S]*?${n}`);J=Q.test(J)?J.replace(Q,Hq):`${J.trim()}
 
 ${Hq}
-`.trimStart(),U(z,J.endsWith(`
+`.trimStart(),X(z,J.endsWith(`
 `)?J:`${J}
-`);let V=$(q,"CLAUDE.md"),Y="";try{Y=H(V,"utf8")}catch{}if(!/@AGENTS\.md/.test(Y))U(V,`${Y?`${Y.trim()}
+`);let V=$(q,"CLAUDE.md"),Y="";try{Y=H(V,"utf8")}catch{}if(!/@AGENTS\.md/.test(Y))X(V,`${Y?`${Y.trim()}
 
 `:""}@AGENTS.md
-`)}function mq(q){let z=$(q,".mcp.json"),J={};try{J=JSON.parse(H(z,"utf8"))}catch{}J.mcpServers=J.mcpServers??{};let Q=J.mcpServers.beacon;if(Q){if(!Q.timeout||Q.timeout<C)return Q.timeout=C,U(z,JSON.stringify(J,null,2)+`
-`),{path:z,added:!1,updated:!0};return{path:z,added:!1,updated:!1}}return J.mcpServers.beacon={command:"beacon",args:["mcp"],timeout:C},U(z,JSON.stringify(J,null,2)+`
-`),{path:z,added:!0,updated:!1}}function Sq(q){let z=$(q,".mcp.json"),J=!1;try{J=!!JSON.parse(H(z,"utf8")).mcpServers?.beacon}catch{}let Q=!1;try{Q=H($(q,"AGENTS.md"),"utf8").includes(R)}catch{}let V=!1;try{V=/@AGENTS\.md/.test(H($(q,"CLAUDE.md"),"utf8"))}catch{}return{repo:q,mcpRegistered:J,agentsMdBlock:Q,claudeMdImport:V,skills:{"beacon-init":v($(q,".claude","skills","beacon-init","SKILL.md")),"beacon-refresh":v($(q,".claude","skills","beacon-refresh","SKILL.md"))},codexSkills:{"beacon-init":v($(q,".agents","skills","beacon-init","SKILL.md")),"beacon-refresh":v($(q,".agents","skills","beacon-refresh","SKILL.md"))}}}function cq(q){let z=[];for(let Z of["beacon-init","beacon-refresh","beacon-db-design"]){let X=$(q,".claude","skills",Z);if(v(X))f(X,{recursive:!0,force:!0}),z.push(Z)}for(let Z of["beacon-init","beacon-refresh"]){let X=$(q,".agents","skills",Z);if(v(X))f(X,{recursive:!0,force:!0}),z.push(`codex:${Z}`)}let J=!1,Q=$(q,".mcp.json");try{let Z=JSON.parse(H(Q,"utf8"));if(Z.mcpServers?.beacon){if(delete Z.mcpServers.beacon,J=!0,Z.mcpServers&&Object.keys(Z.mcpServers).length===0)delete Z.mcpServers;if(Object.keys(Z).length===0)f(Q,{force:!0});else U(Q,JSON.stringify(Z,null,2)+`
-`)}}catch{}let V=!1,Y=$(q,"AGENTS.md");try{let Z=H(Y,"utf8"),X=new RegExp(`\\n?${R}[\\s\\S]*?${s}\\n?`);if(X.test(Z)){let d=Z.replace(X,`
+`)}function cq(q){let z=$(q,".mcp.json"),J={};try{J=JSON.parse(H(z,"utf8"))}catch{}J.mcpServers=J.mcpServers??{};let Q=J.mcpServers.beacon;if(Q){if(!Q.timeout||Q.timeout<f)return Q.timeout=f,X(z,JSON.stringify(J,null,2)+`
+`),{path:z,added:!1,updated:!0};return{path:z,added:!1,updated:!1}}return J.mcpServers.beacon={command:"beacon",args:["mcp"],timeout:f},X(z,JSON.stringify(J,null,2)+`
+`),{path:z,added:!0,updated:!1}}function aq(q){let z=$(q,".mcp.json"),J=!1;try{J=!!JSON.parse(H(z,"utf8")).mcpServers?.beacon}catch{}let Q=!1;try{Q=H($(q,"AGENTS.md"),"utf8").includes(R)}catch{}let V=!1;try{V=/@AGENTS\.md/.test(H($(q,"CLAUDE.md"),"utf8"))}catch{}return{repo:q,mcpRegistered:J,agentsMdBlock:Q,claudeMdImport:V,skills:{"beacon-init":v($(q,".claude","skills","beacon-init","SKILL.md")),"beacon-refresh":v($(q,".claude","skills","beacon-refresh","SKILL.md"))},codexSkills:{"beacon-init":v($(q,".agents","skills","beacon-init","SKILL.md")),"beacon-refresh":v($(q,".agents","skills","beacon-refresh","SKILL.md"))}}}function tq(q){let z=[];for(let Z of["beacon-init","beacon-refresh","beacon-db-design"]){let W=$(q,".claude","skills",Z);if(v(W))F(W,{recursive:!0,force:!0}),z.push(Z)}for(let Z of["beacon-init","beacon-refresh"]){let W=$(q,".agents","skills",Z);if(v(W))F(W,{recursive:!0,force:!0}),z.push(`codex:${Z}`)}let J=!1,Q=$(q,".mcp.json");try{let Z=JSON.parse(H(Q,"utf8"));if(Z.mcpServers?.beacon){if(delete Z.mcpServers.beacon,J=!0,Z.mcpServers&&Object.keys(Z.mcpServers).length===0)delete Z.mcpServers;if(Object.keys(Z).length===0)F(Q,{force:!0});else X(Q,JSON.stringify(Z,null,2)+`
+`)}}catch{}let V=!1,Y=$(q,"AGENTS.md");try{let Z=H(Y,"utf8"),W=new RegExp(`\\n?${R}[\\s\\S]*?${n}\\n?`);if(W.test(Z)){let d=Z.replace(W,`
 `).replace(/\n{3,}/g,`
 
-`).trimStart();U(Y,d.endsWith(`
+`).trimStart();X(Y,d.endsWith(`
 `)?d:`${d}
-`),V=!0}}catch{}let W=!1,P=$(q,"CLAUDE.md");try{let Z=H(P,"utf8"),X=Z.replace(/^[ \t]*@AGENTS\.md[ \t]*\n?/m,"");if(X!==Z){if(!X.trim())f(P,{force:!0});else U(P,X);W=!0}}catch{}return{skillsRemoved:z,mcpUnregistered:J,agentsBlockRemoved:V,claudeImportRemoved:W}}var r=`---
+`),V=!0}}catch{}let U=!1,P=$(q,"CLAUDE.md");try{let Z=H(P,"utf8"),W=Z.replace(/^[ \t]*@AGENTS\.md[ \t]*\n?/m,"");if(W!==Z){if(!W.trim())F(P,{force:!0});else X(P,W);U=!0}}catch{}return{skillsRemoved:z,mcpUnregistered:J,agentsBlockRemoved:V,claudeImportRemoved:U}}var r=`---
 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.
-`,n=`---
+`,s=`---
 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.
 ---
@@ -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.
-`,Lq,R="<!-- beacon:workflow:start -->",s="<!-- beacon:workflow:end -->",Hq;var i=B(()=>{Uq();Lq=[{name:"beacon-init",body:()=>r},{name:"beacon-refresh",body:()=>n}];Hq=`${R}
+`,xq=`---
+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.
+`,mq,R="<!-- beacon:workflow:start -->",n="<!-- beacon:workflow:end -->",Hq;var i=B(()=>{Xq();mq=[{name:"beacon-init",body:()=>r},{name:"beacon-refresh",body:()=>s}];Hq=`${R}
 ## 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:
@@ -229,18 +292,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).
-${s}`});import{existsSync as M,mkdirSync as o,readdirSync as aq,readFileSync as g,rmSync as tq,writeFileSync as T}from"fs";import{dirname as xq,join as x}from"path";function vq(){return!!process.env.CLAUDE_PLUGIN_ROOT}function jq(q=process.env.HOME||process.env.USERPROFILE||""){if(!q)return null;let z=x(q,".claude","plugins");if(!M(z))return null;let J=[z];for(let Q=0;Q<3&&J.length;Q++){let V=[];for(let Y of J){let W=x(Y,".claude-plugin","plugin.json");try{if(M(W)&&JSON.parse(g(W,"utf8")).name==="beacon")return Y}catch{}try{for(let P of aq(Y,{withFileTypes:!0}))if(P.isDirectory())V.push(x(Y,P.name))}catch{}}J=V}return null}function Bq(q){return jq(q)!==null}function e(q){try{return JSON.parse(g(q,"utf8"))}catch{return{}}}function gq(q,z){o(xq(q),{recursive:!0}),T(q,JSON.stringify(z,null,2)+`
-`)}function E(q,z){let J=e(q);J.hooks=J.hooks??{},J.hooks[z.event]=J.hooks[z.event]??[];let Q=J.hooks[z.event];if(Q.some((Y)=>Y.matcher===z.matcher&&Y.hooks?.some((W)=>W.command===z.command)))return!1;return Q.push({matcher:z.matcher,hooks:[{type:"command",command:z.command}]}),gq(q,J),!0}function y(q,z){return(e(q).hooks?.[z.event]??[]).some((V)=>V.hooks?.some((Y)=>Y.command===z.command))}function A(q,z){let J=e(q),Q=J.hooks?.[z.event];if(!Q)return!1;let V=!1,Y=Q.map((W)=>{let P=W.hooks?.length??0,Z=(W.hooks??[]).filter((X)=>X.command!==z.command);if(Z.length!==P)V=!0;return{...W,hooks:Z}}).filter((W)=>(W.hooks??[]).length>0);if(!V)return!1;if(Y.length)J.hooks[z.event]=Y;else delete J.hooks[z.event];if(J.hooks&&Object.keys(J.hooks).length===0)delete J.hooks;return gq(q,J),!0}function D(q,z,J,Q){let V=`${z}
+${n}`});import{existsSync as M,mkdirSync as o,readdirSync as dq,readFileSync as G,rmSync as rq,writeFileSync as T}from"fs";import{dirname as vq,join as x}from"path";function jq(){return!!process.env.CLAUDE_PLUGIN_ROOT}function Bq(q=process.env.HOME||process.env.USERPROFILE||""){if(!q)return null;let z=x(q,".claude","plugins");if(!M(z))return null;let J=[z];for(let Q=0;Q<3&&J.length;Q++){let V=[];for(let Y of J){let U=x(Y,".claude-plugin","plugin.json");try{if(M(U)&&JSON.parse(G(U,"utf8")).name==="beacon")return Y}catch{}try{for(let P of dq(Y,{withFileTypes:!0}))if(P.isDirectory())V.push(x(Y,P.name))}catch{}}J=V}return null}function gq(q){return Bq(q)!==null}function e(q){try{return JSON.parse(G(q,"utf8"))}catch{return{}}}function Gq(q,z){o(vq(q),{recursive:!0}),T(q,JSON.stringify(z,null,2)+`
+`)}function y(q,z){let J=e(q);J.hooks=J.hooks??{},J.hooks[z.event]=J.hooks[z.event]??[];let Q=J.hooks[z.event];if(Q.some((Y)=>Y.matcher===z.matcher&&Y.hooks?.some((U)=>U.command===z.command)))return!1;return Q.push({matcher:z.matcher,hooks:[{type:"command",command:z.command}]}),Gq(q,J),!0}function E(q,z){return(e(q).hooks?.[z.event]??[]).some((V)=>V.hooks?.some((Y)=>Y.command===z.command))}function I(q,z){let J=e(q),Q=J.hooks?.[z.event];if(!Q)return!1;let V=!1,Y=Q.map((U)=>{let P=U.hooks?.length??0,Z=(U.hooks??[]).filter((W)=>W.command!==z.command);if(Z.length!==P)V=!0;return{...U,hooks:Z}}).filter((U)=>(U.hooks??[]).length>0);if(!V)return!1;if(Y.length)J.hooks[z.event]=Y;else delete J.hooks[z.event];if(J.hooks&&Object.keys(J.hooks).length===0)delete J.hooks;return Gq(q,J),!0}function A(q,z,J,Q){let V=`${z}
 ${Q.trim()}
-${J}`,Y="";try{Y=g(q,"utf8")}catch{}let W=new RegExp(`${z}[\\s\\S]*?${J}`);Y=W.test(Y)?Y.replace(W,V):Y.trim()?`${Y.trim()}
+${J}`,Y="";try{Y=G(q,"utf8")}catch{}let U=new RegExp(`${z}[\\s\\S]*?${J}`);Y=U.test(Y)?Y.replace(U,V):Y.trim()?`${Y.trim()}
 
 ${V}
 `:`${V}
-`,o(xq(q),{recursive:!0}),T(q,Y.endsWith(`
+`,o(vq(q),{recursive:!0}),T(q,Y.endsWith(`
 `)?Y:`${Y}
-`)}function N(q,z){try{return g(q,"utf8").includes(z)}catch{return!1}}function O(q,z,J){let Q="";try{Q=g(q,"utf8")}catch{return!1}let V=new RegExp(`${z}[\\s\\S]*?${J}\\n?`);if(!V.test(Q))return!1;let Y=Q.replace(V,"").replace(/\n{3,}/g,`
+`)}function N(q,z){try{return G(q,"utf8").includes(z)}catch{return!1}}function O(q,z,J){let Q="";try{Q=G(q,"utf8")}catch{return!1}let V=new RegExp(`${z}[\\s\\S]*?${J}\\n?`);if(!V.test(Q))return!1;let Y=Q.replace(V,"").replace(/\n{3,}/g,`
 
-`).trimStart();return T(q,Y),!0}function k(q,z,J){let Q=x(q,z);o(Q,{recursive:!0});let V=x(Q,"SKILL.md");return T(V,J),V}function G(q,z){return M(x(q,z,"SKILL.md"))}function h(q,z){let J=x(q,z);if(!M(J))return!1;return tq(J,{recursive:!0,force:!0}),!0}var w,I=`## Beacon (visual planning panel)
+`).trimStart();return T(q,Y),!0}function k(q,z,J){let Q=x(q,z);o(Q,{recursive:!0});let V=x(Q,"SKILL.md");return T(V,J),V}function b(q,z){return M(x(q,z,"SKILL.md"))}function h(q,z){let J=x(q,z);if(!M(J))return!1;return rq(J,{recursive:!0,force:!0}),!0}var w,D=`## 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,
@@ -254,6 +317,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**
@@ -261,17 +327,17 @@ 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 qq=B(()=>{w=["beacon-init","beacon-refresh","beacon-plan"]});import{mkdirSync as dq,renameSync as rq,rmSync as nq,writeFileSync as sq}from"fs";import{dirname as lq}from"path";function L(q,z){dq(lq(q),{recursive:!0});let J=`${q}.tmp`;try{sq(J,z),rq(J,q)}catch(Q){throw nq(J,{force:!0}),Q}}function Iz(q,z,J=!1){L(q,JSON.stringify(z,null,J?2:void 0))}var Nq=()=>{};var Rq={};Xq(Rq,{setupCodexAssets:()=>qz,removeCodexMcp:()=>Fq,removeCodexArtifacts:()=>Jz,hasCodexMcp:()=>Vq,ensureCodexMcp:()=>fq,codexMcpProblem:()=>eq,codexDetected:()=>uq,auditCodex:()=>zz,CODEX_HOOKS:()=>c});import{readFileSync as S}from"fs";import{homedir as iq}from"os";import{join as K}from"path";function Gq(){return process.env.HOME||process.env.USERPROFILE||iq()}function uq(){if(process.env.BEACON_CODEX==="1")return!0;if(process.env.BEACON_CODEX==="0")return!1;if(zq===void 0)zq=Bun.which("codex")!==null;return zq}function u(q){try{return Bun.TOML.parse(q)}catch{return null}}function Vq(){try{return Boolean(u(S(j(),"utf8"))?.mcp_servers?.beacon)}catch{return!1}}function eq(){let q="";try{q=S(j(),"utf8")}catch{return null}let z=u(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 fq(){let q="",z=!1;try{q=S(j(),"utf8"),z=!0}catch{}if(z){let Y=u(q);if(!Y)return{added:!1,error:`~/.codex/config.toml does not parse \u2014 ${b}`};if(Y.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 J=!q?"":q.endsWith(`
+verbatim. Do NOT implement until the tool returns approval.`;var qq=B(()=>{w=["beacon-init","beacon-refresh","beacon-plan","beacon-explain"]});import{mkdirSync as sq,renameSync as nq,rmSync as lq,writeFileSync as iq}from"fs";import{dirname as oq}from"path";function L(q,z){sq(oq(q),{recursive:!0});let J=`${q}.tmp`;try{iq(J,z),nq(J,q)}catch(Q){throw lq(J,{force:!0}),Q}}function Ez(q,z,J=!1){L(q,JSON.stringify(z,null,J?2:void 0))}var Nq=()=>{};var Mq={};Pq(Mq,{setupCodexAssets:()=>Jz,removeCodexMcp:()=>Rq,removeCodexArtifacts:()=>Vz,hasCodexMcp:()=>Vq,ensureCodexMcp:()=>Fq,codexMcpProblem:()=>zz,codexDetected:()=>Kq,auditCodex:()=>Qz,CODEX_HOOKS:()=>c});import{readFileSync as S}from"fs";import{homedir as eq}from"os";import{join as C}from"path";function bq(){return process.env.HOME||process.env.USERPROFILE||eq()}function Kq(){if(process.env.BEACON_CODEX==="1")return!0;if(process.env.BEACON_CODEX==="0")return!1;if(zq===void 0)zq=Bun.which("codex")!==null;return zq}function K(q){try{return Bun.TOML.parse(q)}catch{return null}}function Vq(){try{return Boolean(K(S(j(),"utf8"))?.mcp_servers?.beacon)}catch{return!1}}function zz(){let q="";try{q=S(j(),"utf8")}catch{return null}let z=K(q);if(!z)return`~/.codex/config.toml does not parse \u2014 ${u}`;if(z.mcp_servers?.beacon)return null;if(/^\s*mcp_servers\s*=/m.test(q))return`mcp_servers is an inline table \u2014 ${u}`;return null}function Fq(){let q="",z=!1;try{q=S(j(),"utf8"),z=!0}catch{}if(z){let Y=K(q);if(!Y)return{added:!1,error:`~/.codex/config.toml does not parse \u2014 ${u}`};if(Y.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 ${u}`}}let J=!q?"":q.endsWith(`
 `)?`
 `:`
 
-`,Q=q+J+oq;if(u(Q)?.mcp_servers?.beacon?.command!=="beacon")return{added:!1,error:`could not safely append [mcp_servers.beacon] \u2014 ${b}`};return L(j(),Q),{added:!0}}function Fq(){let q="";try{q=S(j(),"utf8")}catch{return{removed:!1}}let z=q.split(`
-`),J=z.indexOf(Kq);if(J===-1)return{removed:!1,skipped:Vq()};let Q=z.indexOf(Cq,J);if(Q===-1)return{removed:!1,skipped:!0};z.splice(J,Q-J+1);let V=z.join(`
+`,Q=q+J+qz;if(K(Q)?.mcp_servers?.beacon?.command!=="beacon")return{added:!1,error:`could not safely append [mcp_servers.beacon] \u2014 ${u}`};return L(j(),Q),{added:!0}}function Rq(){let q="";try{q=S(j(),"utf8")}catch{return{removed:!1}}let z=q.split(`
+`),J=z.indexOf(Cq);if(J===-1)return{removed:!1,skipped:Vq()};let Q=z.indexOf(fq,J);if(Q===-1)return{removed:!1,skipped:!0};z.splice(J,Q-J+1);let V=z.join(`
 `).replace(/\n{3,}/g,`
 
-`).replace(/^\n+/,"");if(u(V)===null)return{removed:!1,skipped:!0};return L(j(),V),{removed:!0}}async function qz(){let{INIT_SKILL:q,REFRESH_SKILL:z,PLAN_SKILL:J}=await Promise.resolve().then(() => (i(),l)),Q={"beacon-init":q,"beacon-refresh":z,"beacon-plan":J},V=[];for(let Z of w){if(!G(p(),Z))V.push(Z);k(p(),Z,Q[Z])}let Y=0;for(let Z of c)if(E(Qq(),{event:Z.event,matcher:Z.matcher,command:Z.command}))Y++;let W=N(_(),m);D(_(),m,bq,I);let P=fq();return{skillsAdded:V,hooksAdded:Y,agentsMdBlockTouched:!W,mcp:P}}function zz(){let q={};for(let J of w)q[J]=G(p(),J);let z={};for(let J of c)z[J.event]=y(Qq(),{event:J.event,command:J.command});return{detected:uq(),skills:q,hooks:z,agentsMdBlock:N(_(),m),mcp:Vq()}}function Jz(){let q=[];for(let V of w)if(h(p(),V))q.push(V);let z=0;for(let V of c)if(A(Qq(),{event:V.event,command:V.command}))z++;let J=O(_(),m,bq),Q=Fq();return{skillsRemoved:q,hooksRemoved:z,agentsMdBlockRemoved:J,mcpRemoved:Q.removed,mcpSkipped:Q.skipped}}var Jq=()=>K(Gq(),".codex"),Qq=()=>K(Jq(),"hooks.json"),j=()=>K(Jq(),"config.toml"),_=()=>K(Jq(),"AGENTS.md"),p=()=>K(Gq(),".agents","skills"),m="<!-- beacon:global:start -->",bq="<!-- beacon:global:end -->",c,zq,Kq="# beacon:start (managed by Beacon \u2014 `beacon uninstall` removes this block)",Cq="# beacon:end",oq,b="add it manually: codex mcp add beacon -- beacon mcp";var Mq=B(()=>{qq();Nq();c=[{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."}];oq=`${Kq}
+`).replace(/^\n+/,"");if(K(V)===null)return{removed:!1,skipped:!0};return L(j(),V),{removed:!0}}async function Jz(){let{INIT_SKILL:q,REFRESH_SKILL:z,PLAN_SKILL:J,EXPLAIN_SKILL:Q}=await Promise.resolve().then(() => (i(),l)),V={"beacon-init":q,"beacon-refresh":z,"beacon-plan":J,"beacon-explain":Q},Y=[];for(let W of w){if(!b(m(),W))Y.push(W);k(m(),W,V[W])}let U=0;for(let W of c)if(y(Qq(),{event:W.event,matcher:W.matcher,command:W.command}))U++;let P=N(_(),p);A(_(),p,uq,D);let Z=Fq();return{skillsAdded:Y,hooksAdded:U,agentsMdBlockTouched:!P,mcp:Z}}function Qz(){let q={};for(let J of w)q[J]=b(m(),J);let z={};for(let J of c)z[J.event]=E(Qq(),{event:J.event,command:J.command});return{detected:Kq(),skills:q,hooks:z,agentsMdBlock:N(_(),p),mcp:Vq()}}function Vz(){let q=[];for(let V of w)if(h(m(),V))q.push(V);let z=0;for(let V of c)if(I(Qq(),{event:V.event,command:V.command}))z++;let J=O(_(),p,uq),Q=Rq();return{skillsRemoved:q,hooksRemoved:z,agentsMdBlockRemoved:J,mcpRemoved:Q.removed,mcpSkipped:Q.skipped}}var Jq=()=>C(bq(),".codex"),Qq=()=>C(Jq(),"hooks.json"),j=()=>C(Jq(),"config.toml"),_=()=>C(Jq(),"AGENTS.md"),m=()=>C(bq(),".agents","skills"),p="<!-- beacon:global:start -->",uq="<!-- beacon:global:end -->",c,zq,Cq="# beacon:start (managed by Beacon \u2014 `beacon uninstall` removes this block)",fq="# beacon:end",qz,u="add it manually: codex mcp add beacon -- beacon mcp";var Tq=B(()=>{qq();Nq();c=[{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."}];qz=`${Cq}
 [mcp_servers.beacon]
 command = "beacon"
 args = ["mcp"]
-${Cq}
-`});qq();import{existsSync as Qz}from"fs";import{homedir as Vz}from"os";import{join as a}from"path";function Yz(){return process.env.HOME||process.env.USERPROFILE||Vz()}var t=()=>a(Yz(),".claude"),Yq=()=>a(t(),"skills"),Zq=()=>a(t(),"settings.json"),$q=()=>a(t(),"CLAUDE.md"),Wq="<!-- beacon:global:start -->",Tq="<!-- beacon:global:end -->";var Zz=I,Pq=[{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 $z(q,z){return k(Yq(),q,z)}function Iq(q){return G(Yq(),q)}function Wz(q){return h(Yq(),q)}function Pz(q){return E(Zq(),q)}function Xz(q){return y(Zq(),q)}function Uz(q){return A(Zq(),q)}function Hz(q){D($q(),Wq,Tq,q)}function Eq(){return N($q(),Wq)}function wz(){return O($q(),Wq,Tq)}function mz(){let q={};for(let J of w)q[J]=Iq(J);let z={};for(let J of Pq)z[J.event]=Xz({event:J.event,command:J.command});return{homeExists:Qz(t()),skills:q,hooks:z,claudeMdBlock:Eq()}}async function xz(){let{INIT_SKILL:q,REFRESH_SKILL:z,PLAN_SKILL:J}=await Promise.resolve().then(() => (i(),l)),Q={"beacon-init":q,"beacon-refresh":z,"beacon-plan":J},V=[];for(let P of w){if(!Iq(P))V.push(P);$z(P,Q[P])}let Y=0;for(let P of Pq)if(Pz({event:P.event,matcher:P.matcher,command:P.command}))Y++;let W=Eq();return Hz(Zz),{skillsAdded:V,hooksAdded:Y,claudeMdBlockTouched:!W}}async function Sz(){if(vq())return{ok:!0,skipped:"plugin",skillsAdded:[],hooksAdded:0,claudeMdBlockTouched:!1};let q;if(Bq()){try{vz()}catch{}q={ok:!0,skipped:"plugin-present",skillsAdded:[],hooksAdded:0,claudeMdBlockTouched:!1}}else try{q={ok:!0,...await xz()}}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(() => (Mq(),Rq));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 vz(){let q=[];for(let Q of w)if(Wz(Q))q.push(Q);let z=0;for(let Q of Pq)if(Uz(Q))z++;let J=wz();return{skillsRemoved:q,hooksRemoved:z,claudeMdBlockRemoved:J}}export{xz as setupGlobalAssets,Sz as selfHealGlobal,Wz as removeGlobalSkill,Uz as removeGlobalHook,wz as removeGlobalClaudeMdBlock,vz as removeBeaconArtifacts,vq as isPluginManaged,Iq as isGlobalSkillInstalled,$z as installGlobalSkill,Xz as hasGlobalHook,Eq as hasGlobalClaudeMdBlock,jq as findBeaconPluginDir,Pz as ensureGlobalHook,Hz as ensureGlobalClaudeMdBlock,Bq as beaconPluginInstalled,mz as auditGlobal,w as GLOBAL_SKILLS,Pq as GLOBAL_HOOKS,Zz as GLOBAL_CLAUDE_MD_BLOCK};
+${fq}
+`});qq();import{existsSync as Yz}from"fs";import{homedir as Zz}from"os";import{join as a}from"path";function $z(){return process.env.HOME||process.env.USERPROFILE||Zz()}var t=()=>a($z(),".claude"),Yq=()=>a(t(),"skills"),Zq=()=>a(t(),"settings.json"),$q=()=>a(t(),"CLAUDE.md"),Wq="<!-- beacon:global:start -->",Dq="<!-- beacon:global:end -->";var Wz=D,Uq=[{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 Uz(q,z){return k(Yq(),q,z)}function yq(q){return b(Yq(),q)}function Pz(q){return h(Yq(),q)}function Xz(q){return y(Zq(),q)}function Hz(q){return E(Zq(),q)}function wz(q){return I(Zq(),q)}function xz(q){A($q(),Wq,Dq,q)}function Eq(){return N($q(),Wq)}function vz(){return O($q(),Wq,Dq)}function cz(){let q={};for(let J of w)q[J]=yq(J);let z={};for(let J of Uq)z[J.event]=Hz({event:J.event,command:J.command});return{homeExists:Yz(t()),skills:q,hooks:z,claudeMdBlock:Eq()}}async function jz(){let{INIT_SKILL:q,REFRESH_SKILL:z,PLAN_SKILL:J,EXPLAIN_SKILL:Q}=await Promise.resolve().then(() => (i(),l)),V={"beacon-init":q,"beacon-refresh":z,"beacon-plan":J,"beacon-explain":Q},Y=[];for(let Z of w){if(!yq(Z))Y.push(Z);Uz(Z,V[Z])}let U=0;for(let Z of Uq)if(Xz({event:Z.event,matcher:Z.matcher,command:Z.command}))U++;let P=Eq();return xz(Wz),{skillsAdded:Y,hooksAdded:U,claudeMdBlockTouched:!P}}async function az(){if(jq())return{ok:!0,skipped:"plugin",skillsAdded:[],hooksAdded:0,claudeMdBlockTouched:!1};let q;if(gq()){try{Bz()}catch{}q={ok:!0,skipped:"plugin-present",skillsAdded:[],hooksAdded:0,claudeMdBlockTouched:!1}}else try{q={ok:!0,...await jz()}}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(() => (Tq(),Mq));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 Bz(){let q=[];for(let Q of w)if(Pz(Q))q.push(Q);let z=0;for(let Q of Uq)if(wz(Q))z++;let J=vz();return{skillsRemoved:q,hooksRemoved:z,claudeMdBlockRemoved:J}}export{jz as setupGlobalAssets,az as selfHealGlobal,Pz as removeGlobalSkill,wz as removeGlobalHook,vz as removeGlobalClaudeMdBlock,Bz as removeBeaconArtifacts,jq as isPluginManaged,yq as isGlobalSkillInstalled,Uz as installGlobalSkill,Hz as hasGlobalHook,Eq as hasGlobalClaudeMdBlock,Bq as findBeaconPluginDir,Xz as ensureGlobalHook,xz as ensureGlobalClaudeMdBlock,gq as beaconPluginInstalled,cz as auditGlobal,w as GLOBAL_SKILLS,Uq as GLOBAL_HOOKS,Wz as GLOBAL_CLAUDE_MD_BLOCK};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trybeacon",
-  "version": "0.1.65",
+  "version": "0.1.66",
   "description": "The visual planning surface for the coding agent in your terminal.",
   "homepage": "https://trybeacon.sh",
   "license": "Apache-2.0",

package/plugin/skills/beacon-explain/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: beacon-explain
+description: Teach the user part of THIS codebase as an interactive visual lesson on Beacon's /learn page — a concept map + plain-English narrative they can question — 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 — 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 — understanding, not building.
+
+## 1. Load context first — 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 — never vague descriptions.
+
+## 2. Write like a great teacher — 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 — 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 — 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 — 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 / …) 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 — ideally a
+  small markdown table of state transitions — 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 — 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 — one of: imports, calls, persists to, reads from, writes to, routes to, depends
+on, emits, returns, contains, extends — never a bare line. Keep the resting set small (~4–7 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 — 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) — 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.