trybeacon 0.1.65 → 0.1.66

package/dist/bin/hook.js

@@ -1,22 +1,22 @@
 #!/usr/bin/env bun
 // @bun
-var NZ=Object.defineProperty;var PZ=(Q)=>Q;function KZ(Q,Z){this[Q]=PZ.bind(null,Z)}var ZQ=(Q,Z)=>{for(var $ in Z)NZ(Q,$,{get:Z[$],enumerable:!0,configurable:!0,set:KZ.bind(Z,$)})};var K=(Q,Z)=>()=>(Q&&(Z=Q(Q=0)),Z);var y0=1500,L0=480000,k0=1800000,f=3600000,_0=3000;var FQ=()=>{};var VQ={};ZQ(VQ,{removeRepoAssets:()=>FZ,installRefreshSkill:()=>CZ,installPlanSkill:()=>uZ,installInitSkill:()=>vZ,installCodexRepoSkills:()=>wZ,ensureWorkflowDoc:()=>RZ,ensureMcp:()=>TZ,auditRepo:()=>gZ,REFRESH_SKILL:()=>JQ,PLAN_SKILL:()=>bQ,INIT_SKILL:()=>$Q});import{existsSync as v,mkdirSync as A,readFileSync as x,rmSync as I,writeFileSync as H}from"fs";import{join as U}from"path";function vZ(Q){let Z=U(Q,".claude","skills","beacon-init");A(Z,{recursive:!0});let $=U(Z,"SKILL.md");return H($,$Q),$}function CZ(Q){let Z=U(Q,".claude","skills","beacon-refresh");A(Z,{recursive:!0});let $=U(Z,"SKILL.md");return H($,JQ),$}function uZ(Q){let Z=U(Q,".claude","skills","beacon-plan");A(Z,{recursive:!0});let $=U(Z,"SKILL.md");return H($,bQ),$}function wZ(Q){let Z=[];for(let $ of MZ){let J=U(Q,".agents","skills",$.name);A(J,{recursive:!0});let Y=U(J,"SKILL.md");H(Y,$.body()),Z.push(Y)}return Z}function RZ(Q){let Z=U(Q,"AGENTS.md"),$="";try{$=x(Z,"utf8")}catch{}let J=new RegExp(`${E}[\\s\\S]*?${YQ}`);$=J.test($)?$.replace(J,OQ):`${$.trim()}
+var PZ=Object.defineProperty;var KZ=(Q)=>Q;function vZ(Q,Z){this[Q]=KZ.bind(null,Z)}var ZQ=(Q,Z)=>{for(var $ in Z)PZ(Q,$,{get:Z[$],enumerable:!0,configurable:!0,set:vZ.bind(Z,$)})};var K=(Q,Z)=>()=>(Q&&(Z=Q(Q=0)),Z);var L0=1500,_0=480000,S0=1800000,D=3600000,h0=3000;var FQ=()=>{};var VQ={};ZQ(VQ,{removeRepoAssets:()=>bZ,installRefreshSkill:()=>uZ,installPlanSkill:()=>MZ,installInitSkill:()=>CZ,installExplainSkill:()=>wZ,installCodexRepoSkills:()=>TZ,ensureWorkflowDoc:()=>gZ,ensureMcp:()=>FZ,auditRepo:()=>OZ,REFRESH_SKILL:()=>JQ,PLAN_SKILL:()=>bQ,INIT_SKILL:()=>$Q,EXPLAIN_SKILL:()=>fQ});import{existsSync as v,mkdirSync as M,readFileSync as x,rmSync as A,writeFileSync as H}from"fs";import{join as X}from"path";function CZ(Q){let Z=X(Q,".claude","skills","beacon-init");M(Z,{recursive:!0});let $=X(Z,"SKILL.md");return H($,$Q),$}function uZ(Q){let Z=X(Q,".claude","skills","beacon-refresh");M(Z,{recursive:!0});let $=X(Z,"SKILL.md");return H($,JQ),$}function MZ(Q){let Z=X(Q,".claude","skills","beacon-plan");M(Z,{recursive:!0});let $=X(Z,"SKILL.md");return H($,bQ),$}function wZ(Q){let Z=X(Q,".claude","skills","beacon-explain");M(Z,{recursive:!0});let $=X(Z,"SKILL.md");return H($,fQ),$}function TZ(Q){let Z=[];for(let $ of RZ){let J=X(Q,".agents","skills",$.name);M(J,{recursive:!0});let Y=X(J,"SKILL.md");H(Y,$.body()),Z.push(Y)}return Z}function gZ(Q){let Z=X(Q,"AGENTS.md"),$="";try{$=x(Z,"utf8")}catch{}let J=new RegExp(`${E}[\\s\\S]*?${YQ}`);$=J.test($)?$.replace(J,OQ):`${$.trim()}
 
 ${OQ}
 `.trimStart(),H(Z,$.endsWith(`
 `)?$:`${$}
-`);let Y=U(Q,"CLAUDE.md"),V="";try{V=x(Y,"utf8")}catch{}if(!/@AGENTS\.md/.test(V))H(Y,`${V?`${V.trim()}
+`);let Y=X(Q,"CLAUDE.md"),V="";try{V=x(Y,"utf8")}catch{}if(!/@AGENTS\.md/.test(V))H(Y,`${V?`${V.trim()}
 
 `:""}@AGENTS.md
-`)}function TZ(Q){let Z=U(Q,".mcp.json"),$={};try{$=JSON.parse(x(Z,"utf8"))}catch{}$.mcpServers=$.mcpServers??{};let J=$.mcpServers.beacon;if(J){if(!J.timeout||J.timeout<f)return J.timeout=f,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:f},H(Z,JSON.stringify($,null,2)+`
-`),{path:Z,added:!0,updated:!1}}function gZ(Q){let Z=U(Q,".mcp.json"),$=!1;try{$=!!JSON.parse(x(Z,"utf8")).mcpServers?.beacon}catch{}let J=!1;try{J=x(U(Q,"AGENTS.md"),"utf8").includes(E)}catch{}let Y=!1;try{Y=/@AGENTS\.md/.test(x(U(Q,"CLAUDE.md"),"utf8"))}catch{}return{repo:Q,mcpRegistered:$,agentsMdBlock:J,claudeMdImport:Y,skills:{"beacon-init":v(U(Q,".claude","skills","beacon-init","SKILL.md")),"beacon-refresh":v(U(Q,".claude","skills","beacon-refresh","SKILL.md"))},codexSkills:{"beacon-init":v(U(Q,".agents","skills","beacon-init","SKILL.md")),"beacon-refresh":v(U(Q,".agents","skills","beacon-refresh","SKILL.md"))}}}function FZ(Q){let Z=[];for(let z of["beacon-init","beacon-refresh","beacon-db-design"]){let W=U(Q,".claude","skills",z);if(v(W))I(W,{recursive:!0,force:!0}),Z.push(z)}for(let z of["beacon-init","beacon-refresh"]){let W=U(Q,".agents","skills",z);if(v(W))I(W,{recursive:!0,force:!0}),Z.push(`codex:${z}`)}let $=!1,J=U(Q,".mcp.json");try{let z=JSON.parse(x(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)I(J,{force:!0});else H(J,JSON.stringify(z,null,2)+`
-`)}}catch{}let Y=!1,V=U(Q,"AGENTS.md");try{let z=x(V,"utf8"),W=new RegExp(`\\n?${E}[\\s\\S]*?${YQ}\\n?`);if(W.test(z)){let QQ=z.replace(W,`
+`)}function FZ(Q){let Z=X(Q,".mcp.json"),$={};try{$=JSON.parse(x(Z,"utf8"))}catch{}$.mcpServers=$.mcpServers??{};let J=$.mcpServers.beacon;if(J){if(!J.timeout||J.timeout<D)return J.timeout=D,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:D},H(Z,JSON.stringify($,null,2)+`
+`),{path:Z,added:!0,updated:!1}}function OZ(Q){let Z=X(Q,".mcp.json"),$=!1;try{$=!!JSON.parse(x(Z,"utf8")).mcpServers?.beacon}catch{}let J=!1;try{J=x(X(Q,"AGENTS.md"),"utf8").includes(E)}catch{}let Y=!1;try{Y=/@AGENTS\.md/.test(x(X(Q,"CLAUDE.md"),"utf8"))}catch{}return{repo:Q,mcpRegistered:$,agentsMdBlock:J,claudeMdImport:Y,skills:{"beacon-init":v(X(Q,".claude","skills","beacon-init","SKILL.md")),"beacon-refresh":v(X(Q,".claude","skills","beacon-refresh","SKILL.md"))},codexSkills:{"beacon-init":v(X(Q,".agents","skills","beacon-init","SKILL.md")),"beacon-refresh":v(X(Q,".agents","skills","beacon-refresh","SKILL.md"))}}}function bZ(Q){let Z=[];for(let z of["beacon-init","beacon-refresh","beacon-db-design"]){let U=X(Q,".claude","skills",z);if(v(U))A(U,{recursive:!0,force:!0}),Z.push(z)}for(let z of["beacon-init","beacon-refresh"]){let U=X(Q,".agents","skills",z);if(v(U))A(U,{recursive:!0,force:!0}),Z.push(`codex:${z}`)}let $=!1,J=X(Q,".mcp.json");try{let z=JSON.parse(x(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)A(J,{force:!0});else H(J,JSON.stringify(z,null,2)+`
+`)}}catch{}let Y=!1,V=X(Q,"AGENTS.md");try{let z=x(V,"utf8"),U=new RegExp(`\\n?${E}[\\s\\S]*?${YQ}\\n?`);if(U.test(z)){let QQ=z.replace(U,`
 `).replace(/\n{3,}/g,`
 
 `).trimStart();H(V,QQ.endsWith(`
 `)?QQ:`${QQ}
-`),Y=!0}}catch{}let q=!1,X=U(Q,"CLAUDE.md");try{let z=x(X,"utf8"),W=z.replace(/^[ \t]*@AGENTS\.md[ \t]*\n?/m,"");if(W!==z){if(!W.trim())I(X,{force:!0});else H(X,W);q=!0}}catch{}return{skillsRemoved:Z,mcpUnregistered:$,agentsBlockRemoved:Y,claudeImportRemoved:q}}var $Q=`---
+`),Y=!0}}catch{}let q=!1,W=X(Q,"CLAUDE.md");try{let z=x(W,"utf8"),U=z.replace(/^[ \t]*@AGENTS\.md[ \t]*\n?/m,"");if(U!==z){if(!U.trim())A(W,{force:!0});else H(W,U);q=!0}}catch{}return{skillsRemoved:Z,mcpUnregistered:$,agentsBlockRemoved:Y,claudeImportRemoved:q}}var $Q=`---
 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.
 ---
@@ -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.
-`,MZ,E="<!-- beacon:workflow:start -->",YQ="<!-- beacon:workflow:end -->",OQ;var zQ=K(()=>{FQ();MZ=[{name:"beacon-init",body:()=>$Q},{name:"beacon-refresh",body:()=>JQ}];OQ=`${E}
+`,fQ=`---
+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.
+`,RZ,E="<!-- beacon:workflow:start -->",YQ="<!-- beacon:workflow:end -->",OQ;var zQ=K(()=>{FQ();RZ=[{name:"beacon-init",body:()=>$Q},{name:"beacon-refresh",body:()=>JQ}];OQ=`${E}
 ## 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:
@@ -230,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).
-${YQ}`});import{existsSync as D,mkdirSync as qQ,readdirSync as OZ,readFileSync as M,rmSync as bZ,writeFileSync as y}from"fs";import{dirname as fQ,join as N}from"path";function IQ(){return!!process.env.CLAUDE_PLUGIN_ROOT}function AQ(Q=process.env.HOME||process.env.USERPROFILE||""){if(!Q)return null;let Z=N(Q,".claude","plugins");if(!D(Z))return null;let $=[Z];for(let J=0;J<3&&$.length;J++){let Y=[];for(let V of $){let q=N(V,".claude-plugin","plugin.json");try{if(D(q)&&JSON.parse(M(q,"utf8")).name==="beacon")return V}catch{}try{for(let X of OZ(V,{withFileTypes:!0}))if(X.isDirectory())Y.push(N(V,X.name))}catch{}}$=Y}return null}function EQ(Q){return AQ(Q)!==null}function XQ(Q){try{return JSON.parse(M(Q,"utf8"))}catch{return{}}}function DQ(Q,Z){qQ(fQ(Q),{recursive:!0}),y(Q,JSON.stringify(Z,null,2)+`
-`)}function k(Q,Z){let $=XQ(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}]}),DQ(Q,$),!0}function _(Q,Z){return(XQ(Q).hooks?.[Z.event]??[]).some((Y)=>Y.hooks?.some((V)=>V.command===Z.command))}function S(Q,Z){let $=XQ(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 DQ(Q,$),!0}function h(Q,Z,$,J){let Y=`${Z}
+${YQ}`});import{existsSync as I,mkdirSync as qQ,readdirSync as fZ,readFileSync as w,rmSync as DZ,writeFileSync as y}from"fs";import{dirname as DQ,join as N}from"path";function AQ(){return!!process.env.CLAUDE_PLUGIN_ROOT}function EQ(Q=process.env.HOME||process.env.USERPROFILE||""){if(!Q)return null;let Z=N(Q,".claude","plugins");if(!I(Z))return null;let $=[Z];for(let J=0;J<3&&$.length;J++){let Y=[];for(let V of $){let q=N(V,".claude-plugin","plugin.json");try{if(I(q)&&JSON.parse(w(q,"utf8")).name==="beacon")return V}catch{}try{for(let W of fZ(V,{withFileTypes:!0}))if(W.isDirectory())Y.push(N(V,W.name))}catch{}}$=Y}return null}function IQ(Q){return EQ(Q)!==null}function XQ(Q){try{return JSON.parse(w(Q,"utf8"))}catch{return{}}}function yQ(Q,Z){qQ(DQ(Q),{recursive:!0}),y(Q,JSON.stringify(Z,null,2)+`
+`)}function L(Q,Z){let $=XQ(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}]}),yQ(Q,$),!0}function _(Q,Z){return(XQ(Q).hooks?.[Z.event]??[]).some((Y)=>Y.hooks?.some((V)=>V.command===Z.command))}function S(Q,Z){let $=XQ(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 yQ(Q,$),!0}function h(Q,Z,$,J){let Y=`${Z}
 ${J.trim()}
-${$}`,V="";try{V=M(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=w(Q,"utf8")}catch{}let q=new RegExp(`${Z}[\\s\\S]*?${$}`);V=q.test(V)?V.replace(q,Y):V.trim()?`${V.trim()}
 
 ${Y}
 `:`${Y}
-`,qQ(fQ(Q),{recursive:!0}),y(Q,V.endsWith(`
+`,qQ(DQ(Q),{recursive:!0}),y(Q,V.endsWith(`
 `)?V:`${V}
-`)}function w(Q,Z){try{return M(Q,"utf8").includes(Z)}catch{return!1}}function m(Q,Z,$){let J="";try{J=M(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 R(Q,Z){try{return w(Q,"utf8").includes(Z)}catch{return!1}}function m(Q,Z,$){let J="";try{J=w(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 y(Q,V),!0}function p(Q,Z,$){let J=N(Q,Z);qQ(J,{recursive:!0});let Y=N(J,"SKILL.md");return y(Y,$),Y}function R(Q,Z){return D(N(Q,Z,"SKILL.md"))}function c(Q,Z){let $=N(Q,Z);if(!D($))return!1;return bZ($,{recursive:!0,force:!0}),!0}var j,L=`## Beacon (visual planning panel)
+`).trimStart();return y(Q,V),!0}function p(Q,Z,$){let J=N(Q,Z);qQ(J,{recursive:!0});let Y=N(J,"SKILL.md");return y(Y,$),Y}function T(Q,Z){return I(N(Q,Z,"SKILL.md"))}function c(Q,Z){let $=N(Q,Z);if(!I($))return!1;return DZ($,{recursive:!0,force:!0}),!0}var j,k=`## 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,
@@ -255,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**
@@ -262,18 +328,18 @@ 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=K(()=>{j=["beacon-init","beacon-refresh","beacon-plan"]});import{mkdirSync as fZ,renameSync as IZ,rmSync as AZ,writeFileSync as EZ}from"fs";import{dirname as DZ}from"path";function n(Q,Z){fZ(DZ(Q),{recursive:!0});let $=`${Q}.tmp`;try{EZ($,Z),IZ($,Q)}catch(J){throw AZ($,{force:!0}),J}}function s0(Q,Z,$=!1){n(Q,JSON.stringify(Z,null,$?2:void 0))}var yQ=()=>{};var cQ={};ZQ(cQ,{setupCodexAssets:()=>_Z,removeCodexMcp:()=>pQ,removeCodexArtifacts:()=>hZ,hasCodexMcp:()=>BQ,ensureCodexMcp:()=>mQ,codexMcpProblem:()=>kZ,codexDetected:()=>_Q,auditCodex:()=>SZ,CODEX_HOOKS:()=>t});import{readFileSync as s}from"fs";import{homedir as yZ}from"os";import{join as F}from"path";function LQ(){return process.env.HOME||process.env.USERPROFILE||yZ()}function _Q(){if(process.env.BEACON_CODEX==="1")return!0;if(process.env.BEACON_CODEX==="0")return!1;if(WQ===void 0)WQ=Bun.which("codex")!==null;return WQ}function g(Q){try{return Bun.TOML.parse(Q)}catch{return null}}function BQ(){try{return Boolean(g(s(C(),"utf8"))?.mcp_servers?.beacon)}catch{return!1}}function kZ(){let Q="";try{Q=s(C(),"utf8")}catch{return null}let Z=g(Q);if(!Z)return`~/.codex/config.toml does not parse \u2014 ${T}`;if(Z.mcp_servers?.beacon)return null;if(/^\s*mcp_servers\s*=/m.test(Q))return`mcp_servers is an inline table \u2014 ${T}`;return null}function mQ(){let Q="",Z=!1;try{Q=s(C(),"utf8"),Z=!0}catch{}if(Z){let V=g(Q);if(!V)return{added:!1,error:`~/.codex/config.toml does not parse \u2014 ${T}`};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 ${T}`}}let $=!Q?"":Q.endsWith(`
+verbatim. Do NOT implement until the tool returns approval.`;var UQ=K(()=>{j=["beacon-init","beacon-refresh","beacon-plan","beacon-explain"]});import{mkdirSync as AZ,renameSync as EZ,rmSync as IZ,writeFileSync as yZ}from"fs";import{dirname as kZ}from"path";function l(Q,Z){AZ(kZ(Q),{recursive:!0});let $=`${Q}.tmp`;try{yZ($,Z),EZ($,Q)}catch(J){throw IZ($,{force:!0}),J}}function r0(Q,Z,$=!1){l(Q,JSON.stringify(Z,null,$?2:void 0))}var kQ=()=>{};var lQ={};ZQ(lQ,{setupCodexAssets:()=>hZ,removeCodexMcp:()=>cQ,removeCodexArtifacts:()=>pZ,hasCodexMcp:()=>BQ,ensureCodexMcp:()=>pQ,codexMcpProblem:()=>SZ,codexDetected:()=>SQ,auditCodex:()=>mZ,CODEX_HOOKS:()=>t});import{readFileSync as s}from"fs";import{homedir as LZ}from"os";import{join as O}from"path";function LQ(){return process.env.HOME||process.env.USERPROFILE||LZ()}function SQ(){if(process.env.BEACON_CODEX==="1")return!0;if(process.env.BEACON_CODEX==="0")return!1;if(WQ===void 0)WQ=Bun.which("codex")!==null;return WQ}function F(Q){try{return Bun.TOML.parse(Q)}catch{return null}}function BQ(){try{return Boolean(F(s(C(),"utf8"))?.mcp_servers?.beacon)}catch{return!1}}function SZ(){let Q="";try{Q=s(C(),"utf8")}catch{return null}let Z=F(Q);if(!Z)return`~/.codex/config.toml does not parse \u2014 ${g}`;if(Z.mcp_servers?.beacon)return null;if(/^\s*mcp_servers\s*=/m.test(Q))return`mcp_servers is an inline table \u2014 ${g}`;return null}function pQ(){let Q="",Z=!1;try{Q=s(C(),"utf8"),Z=!0}catch{}if(Z){let V=F(Q);if(!V)return{added:!1,error:`~/.codex/config.toml does not parse \u2014 ${g}`};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 ${g}`}}let $=!Q?"":Q.endsWith(`
 `)?`
 `:`
 
-`,J=Q+$+LZ;if(g(J)?.mcp_servers?.beacon?.command!=="beacon")return{added:!1,error:`could not safely append [mcp_servers.beacon] \u2014 ${T}`};return n(C(),J),{added:!0}}function pQ(){let Q="";try{Q=s(C(),"utf8")}catch{return{removed:!1}}let Z=Q.split(`
-`),$=Z.indexOf(SQ);if($===-1)return{removed:!1,skipped:BQ()};let J=Z.indexOf(hQ,$);if(J===-1)return{removed:!1,skipped:!0};Z.splice($,J-$+1);let Y=Z.join(`
+`,J=Q+$+_Z;if(F(J)?.mcp_servers?.beacon?.command!=="beacon")return{added:!1,error:`could not safely append [mcp_servers.beacon] \u2014 ${g}`};return l(C(),J),{added:!0}}function cQ(){let Q="";try{Q=s(C(),"utf8")}catch{return{removed:!1}}let Z=Q.split(`
+`),$=Z.indexOf(hQ);if($===-1)return{removed:!1,skipped:BQ()};let J=Z.indexOf(mQ,$);if(J===-1)return{removed:!1,skipped:!0};Z.splice($,J-$+1);let Y=Z.join(`
 `).replace(/\n{3,}/g,`
 
-`).replace(/^\n+/,"");if(g(Y)===null)return{removed:!1,skipped:!0};return n(C(),Y),{removed:!0}}async function _Z(){let{INIT_SKILL:Q,REFRESH_SKILL:Z,PLAN_SKILL:$}=await Promise.resolve().then(() => (zQ(),VQ)),J={"beacon-init":Q,"beacon-refresh":Z,"beacon-plan":$},Y=[];for(let z of j){if(!R(d(),z))Y.push(z);p(d(),z,J[z])}let V=0;for(let z of t)if(k(xQ(),{event:z.event,matcher:z.matcher,command:z.command}))V++;let q=w(l(),a);h(l(),a,kQ,L);let X=mQ();return{skillsAdded:Y,hooksAdded:V,agentsMdBlockTouched:!q,mcp:X}}function SZ(){let Q={};for(let $ of j)Q[$]=R(d(),$);let Z={};for(let $ of t)Z[$.event]=_(xQ(),{event:$.event,command:$.command});return{detected:_Q(),skills:Q,hooks:Z,agentsMdBlock:w(l(),a),mcp:BQ()}}function hZ(){let Q=[];for(let Y of j)if(c(d(),Y))Q.push(Y);let Z=0;for(let Y of t)if(S(xQ(),{event:Y.event,command:Y.command}))Z++;let $=m(l(),a,kQ),J=pQ();return{skillsRemoved:Q,hooksRemoved:Z,agentsMdBlockRemoved:$,mcpRemoved:J.removed,mcpSkipped:J.skipped}}var HQ=()=>F(LQ(),".codex"),xQ=()=>F(HQ(),"hooks.json"),C=()=>F(HQ(),"config.toml"),l=()=>F(HQ(),"AGENTS.md"),d=()=>F(LQ(),".agents","skills"),a="<!-- beacon:global:start -->",kQ="<!-- beacon:global:end -->",t,WQ,SQ="# beacon:start (managed by Beacon \u2014 `beacon uninstall` removes this block)",hQ="# beacon:end",LZ,T="add it manually: codex mcp add beacon -- beacon mcp";var nQ=K(()=>{UQ();yQ();t=[{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."}];LZ=`${SQ}
+`).replace(/^\n+/,"");if(F(Y)===null)return{removed:!1,skipped:!0};return l(C(),Y),{removed:!0}}async function hZ(){let{INIT_SKILL:Q,REFRESH_SKILL:Z,PLAN_SKILL:$,EXPLAIN_SKILL:J}=await Promise.resolve().then(() => (zQ(),VQ)),Y={"beacon-init":Q,"beacon-refresh":Z,"beacon-plan":$,"beacon-explain":J},V=[];for(let U of j){if(!T(d(),U))V.push(U);p(d(),U,Y[U])}let q=0;for(let U of t)if(L(xQ(),{event:U.event,matcher:U.matcher,command:U.command}))q++;let W=R(n(),a);h(n(),a,_Q,k);let z=pQ();return{skillsAdded:V,hooksAdded:q,agentsMdBlockTouched:!W,mcp:z}}function mZ(){let Q={};for(let $ of j)Q[$]=T(d(),$);let Z={};for(let $ of t)Z[$.event]=_(xQ(),{event:$.event,command:$.command});return{detected:SQ(),skills:Q,hooks:Z,agentsMdBlock:R(n(),a),mcp:BQ()}}function pZ(){let Q=[];for(let Y of j)if(c(d(),Y))Q.push(Y);let Z=0;for(let Y of t)if(S(xQ(),{event:Y.event,command:Y.command}))Z++;let $=m(n(),a,_Q),J=cQ();return{skillsRemoved:Q,hooksRemoved:Z,agentsMdBlockRemoved:$,mcpRemoved:J.removed,mcpSkipped:J.skipped}}var HQ=()=>O(LQ(),".codex"),xQ=()=>O(HQ(),"hooks.json"),C=()=>O(HQ(),"config.toml"),n=()=>O(HQ(),"AGENTS.md"),d=()=>O(LQ(),".agents","skills"),a="<!-- beacon:global:start -->",_Q="<!-- beacon:global:end -->",t,WQ,hQ="# beacon:start (managed by Beacon \u2014 `beacon uninstall` removes this block)",mQ="# beacon:end",_Z,g="add it manually: codex mcp add beacon -- beacon mcp";var nQ=K(()=>{UQ();kQ();t=[{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."}];_Z=`${hQ}
 [mcp_servers.beacon]
 command = "beacon"
 args = ["mcp"]
-${hQ}
-`});var rQ={};ZQ(rQ,{provisionDb:()=>H0});import{createClient as Q0}from"@libsql/client";import{drizzle as Z0}from"drizzle-orm/libsql";import{migrate as $0}from"drizzle-orm/libsql/migrator";import{readMigrationFiles as J0}from"drizzle-orm/migrator";import{dirname as vQ,join as Y0}from"path";import{fileURLToPath as V0}from"url";async function i(Q,Z){return(await Q.execute({sql:"SELECT 1 FROM sqlite_master WHERE type='table' AND name = ?",args:[Z]})).rows.length>0}async function U0(Q,Z){let $=await Q.execute(`PRAGMA table_info("${Z}")`);return new Set($.rows.map((J)=>String(J.name)))}async function tQ(Q){if(!await i(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 W0(Q){for(let[Z,$]of Object.entries(X0)){if(!await i(Q,Z))continue;let J=await U0(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 H0(Q,Z=q0){let $=Q0({url:Q});try{await $.execute("PRAGMA journal_mode = WAL;"),await $.execute("PRAGMA foreign_keys = ON;"),await $.execute("PRAGMA busy_timeout = 5000;");let J=await i($,"__drizzle_migrations"),Y=await i($,"Node"),V=!1;if(Y&&!J){let X=J0({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 tQ($);if(await $0(Z0($),{migrationsFolder:Z}),await tQ($)>q)V=!0;return await W0($),{migrated:V}}finally{$.close()}}var z0,q0,X0;var oQ=K(async()=>{z0=vQ(vQ(vQ(V0(import.meta.url)))),q0=process.env.BEACON_MIGRATIONS_DIR||Y0(z0,"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"]}});UQ();import{existsSync as mZ}from"fs";import{homedir as pZ}from"os";import{join as r}from"path";function cZ(){return process.env.HOME||process.env.USERPROFILE||pZ()}var o=()=>r(cZ(),".claude"),jQ=()=>r(o(),"skills"),GQ=()=>r(o(),"settings.json"),NQ=()=>r(o(),"CLAUDE.md"),PQ="<!-- beacon:global:start -->",lQ="<!-- beacon:global:end -->";var nZ=L,KQ=[{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 lZ(Q,Z){return p(jQ(),Q,Z)}function dQ(Q){return R(jQ(),Q)}function dZ(Q){return c(jQ(),Q)}function aZ(Q){return k(GQ(),Q)}function sZ(Q){return _(GQ(),Q)}function tZ(Q){return S(GQ(),Q)}function rZ(Q){h(NQ(),PQ,lQ,Q)}function aQ(){return w(NQ(),PQ)}function oZ(){return m(NQ(),PQ,lQ)}function V1(){let Q={};for(let $ of j)Q[$]=dQ($);let Z={};for(let $ of KQ)Z[$.event]=sZ({event:$.event,command:$.command});return{homeExists:mZ(o()),skills:Q,hooks:Z,claudeMdBlock:aQ()}}async function iZ(){let{INIT_SKILL:Q,REFRESH_SKILL:Z,PLAN_SKILL:$}=await Promise.resolve().then(() => (zQ(),VQ)),J={"beacon-init":Q,"beacon-refresh":Z,"beacon-plan":$},Y=[];for(let X of j){if(!dQ(X))Y.push(X);lZ(X,J[X])}let V=0;for(let X of KQ)if(aZ({event:X.event,matcher:X.matcher,command:X.command}))V++;let q=aQ();return rZ(nZ),{skillsAdded:Y,hooksAdded:V,claudeMdBlockTouched:!q}}async function sQ(){if(IQ())return{ok:!0,skipped:"plugin",skillsAdded:[],hooksAdded:0,claudeMdBlockTouched:!1};let Q;if(EQ()){try{eZ()}catch{}Q={ok:!0,skipped:"plugin-present",skillsAdded:[],hooksAdded:0,claudeMdBlockTouched:!1}}else try{Q={ok:!0,...await iZ()}}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(() => (nQ(),cQ));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 eZ(){let Q=[];for(let J of j)if(dZ(J))Q.push(J);let Z=0;for(let J of KQ)if(tZ(J))Z++;let $=oZ();return{skillsRemoved:Q,hooksRemoved:Z,claudeMdBlockRemoved:$}}import{AsyncLocalStorage as x0}from"async_hooks";import{spawnSync as B0}from"child_process";import{createHash as j0}from"crypto";import{existsSync as eQ,mkdirSync as O,readFileSync as uQ,writeFileSync as MQ}from"fs";import{homedir as QZ}from"os";import{basename as G0,join as G,parse as N0,resolve as iQ}from"path";function B(){return process.env.BEACON_HOME||G(QZ(),".beacon")}function wQ(){return G(B(),"workspaces.json")}function u(Q){return j0("sha256").update(Q).digest("hex").slice(0,12)}function ZZ(Q=process.cwd()){let Z=B0("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 $Z(Q){let Z=iQ(Q);return Z!==iQ(QZ())&&Z!==N0(Z).root}function JZ(){return G(B(),"deleted.json")}function RQ(){try{let Q=JSON.parse(uQ(JZ(),"utf8"));return Array.isArray(Q)?Q:[]}catch{return[]}}function YZ(Q){O(B(),{recursive:!0}),MQ(JZ(),JSON.stringify(Q,null,2))}function VZ(Q){return RQ().includes(Q)}function v1(Q){let Z=RQ();if(!Z.includes(Q))YZ([...Z,Q])}function P0(Q){let Z=RQ();if(Z.includes(Q))YZ(Z.filter(($)=>$!==Q))}function e(Q){return G(B(),Q)}function K0(Q){return`file:${G(e(Q),"db.sqlite")}`}function b(){try{let Q=JSON.parse(uQ(wQ(),"utf8"));return Array.isArray(Q)?Q:[]}catch{return[]}}function TQ(Q){O(B(),{recursive:!0}),MQ(wQ(),JSON.stringify(Q,null,2))}function zZ(){return b().sort((Q,Z)=>Z.lastOpenedAt.localeCompare(Q.lastOpenedAt))}function P(Q){return b().find((Z)=>Z.id===Q)??null}function qZ(Q,Z,$=new Date().toISOString()){if(!$Z(Q))throw Error(`beacon: refusing to register a non-repo path as a workspace: ${Q}`);let J=u(Q);if(VZ(J))throw Error(`beacon: workspace ${J} (${Q}) was deleted \u2014 run \`beacon\` or /beacon-init to re-add it`);let Y=b(),V=Y.find((z)=>z.id===J),q={id:J,path:Q,name:Z||V?.name||G0(Q),lastOpenedAt:$},X=[q,...Y.filter((z)=>z.id!==J)];return O(e(J),{recursive:!0}),TQ(X),q}function C1(Q,Z){return P0(u(Q)),qZ(Q,Z)}function u1(Q,Z=new Date().toISOString()){let $=b(),J=$.find((Y)=>Y.id===Q);if(!J)return;J.lastOpenedAt=Z,TQ($)}function M1(Q){if(TQ(b().filter((Z)=>Z.id!==Q)),gQ()===Q)v0(zZ()[0]?.id??null)}function XZ(){return G(B(),"active")}function gQ(){try{return uQ(XZ(),"utf8").trim()||null}catch{return null}}function v0(Q){O(B(),{recursive:!0}),MQ(XZ(),Q??"")}function w1(){let Q=gQ();return Q?P(Q):null}function R1(){let Q=M0()??gQ();return Q?P(Q):null}function T1(Q){return P(Q)?.path??null}function g1(){return eQ(wQ())}var UZ="beacon_ws";function WZ(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 F1(Q){let Z=Q.headers.get("x-beacon-workspace");if(Z&&P(Z))return Z;let $=WZ(Q,UZ);if($&&P($))return $;return C0()}function C0(){let Q=zZ();return Q.length===1?Q[0].id:null}var u0="x-beacon-workspace-path";async function O1(Q){let Z=Q.headers.get("x-beacon-workspace");if(Z&&P(Z))return Z;let $=Q.headers.get(u0);if($&&$Z($)&&!VZ(u($))&&(!Z||u($)===Z)){let Y=qZ($);return await w0(Y.id),Y.id}let J=WZ(Q,UZ);if(J&&P(J))return J;return null}var HZ=new x0;function b1(Q,Z){return Q?HZ.run(Q,Z):Z()}function M0(){return HZ.getStore()??null}var CQ=new Set;function f1(Q){CQ.delete(G(e(Q),"db.sqlite"))}async function w0(Q){let Z=e(Q),$=G(Z,"db.sqlite"),J=eQ($);if(J&&CQ.has($))return{ok:!0,created:!1,migrated:!1};try{O(Z,{recursive:!0});let{provisionDb:Y}=await oQ().then(() => rQ),V=await Y(K0(Q));return CQ.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)}}}import{connect as R0}from"net";var xZ=4319;function T0(Q,Z,$=400){return new Promise((J)=>{let Y=R0({host:Q,port:Z}),V=!1,q=(X)=>{if(V)return;V=!0,Y.destroy(),J(X)};Y.once("connect",()=>q(!0)),Y.once("error",()=>q(!1)),Y.setTimeout($,()=>q(!1))})}async function g0(Q){for(let Z of["127.0.0.1","::1"])if(await T0(Z,Q))return!1;return!0}async function E1(Q,Z=20){for(let $=Q;$<Q+Z;$++)if(await g0($))return $;return Q}import{resolve as F0}from"path";var O0="*** Begin Patch",b0=/^\*\*\* (Update File|Add File|Move to): (.+)$/;function f0(Q){let Z=[];for(let $ of Q.split(`
-`)){let J=b0.exec($.trim());if(!J)continue;let Y=J[2].trim();if(J[1]==="Move to")Z.pop();Z.push(Y)}return Z}function BZ(Q){let Z=Q.tool_input;if(Z===null||typeof Z!=="object")return[];let $=Z,J=[];if(typeof $.file_path==="string")J.push($.file_path);if(typeof $.path==="string")J.push($.path);if(Array.isArray($.files))for(let V of $.files){let q=V?.file_path;if(typeof q==="string")J.push(q)}if(J.length)return J;let Y=typeof Q.cwd==="string"?Q.cwd:process.cwd();for(let V of Object.values($)){if(typeof V!=="string"||!V.includes(O0))continue;return f0(V).map((q)=>F0(Y,q))}return[]}import{readFileSync as I0}from"fs";import{join as A0}from"path";function E0(){try{return JSON.parse(I0(A0(B(),"server.json"),"utf8"))}catch{return null}}function jZ(){if(process.env.BEACON_URL)return process.env.BEACON_URL;return`http://localhost:${E0()?.port||process.env.PORT||xZ}`}await sQ();var GZ="";for await(let Q of process.stdin)GZ+=Q;try{let Q=JSON.parse(GZ||"{}"),Z=BZ(Q);if(Z.length){let $=u(ZZ(typeof Q.cwd==="string"?Q.cwd:void 0));await fetch(`${jZ()}/api/map/touch-active`,{method:"POST",headers:{"content-type":"application/json","x-beacon-workspace":$},body:JSON.stringify({files:Z})}).catch(()=>{})}}catch{}process.exit(0);
+${mQ}
+`});var oQ={};ZQ(oQ,{provisionDb:()=>B0});import{createClient as $0}from"@libsql/client";import{drizzle as J0}from"drizzle-orm/libsql";import{migrate as Y0}from"drizzle-orm/libsql/migrator";import{readMigrationFiles as V0}from"drizzle-orm/migrator";import{dirname as vQ,join as z0}from"path";import{fileURLToPath as q0}from"url";async function i(Q,Z){return(await Q.execute({sql:"SELECT 1 FROM sqlite_master WHERE type='table' AND name = ?",args:[Z]})).rows.length>0}async function H0(Q,Z){let $=await Q.execute(`PRAGMA table_info("${Z}")`);return new Set($.rows.map((J)=>String(J.name)))}async function rQ(Q){if(!await i(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(W0)){if(!await i(Q,Z))continue;let J=await H0(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 B0(Q,Z=U0){let $=$0({url:Q});try{await $.execute("PRAGMA journal_mode = WAL;"),await $.execute("PRAGMA foreign_keys = ON;"),await $.execute("PRAGMA busy_timeout = 5000;");let J=await i($,"__drizzle_migrations"),Y=await i($,"Node"),V=!1;if(Y&&!J){let W=V0({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 rQ($);if(await Y0(J0($),{migrationsFolder:Z}),await rQ($)>q)V=!0;return await x0($),{migrated:V}}finally{$.close()}}var X0,U0,W0;var iQ=K(async()=>{X0=vQ(vQ(vQ(q0(import.meta.url)))),U0=process.env.BEACON_MIGRATIONS_DIR||z0(X0,"drizzle"),W0={Node:["createdAt","updatedAt"],Note:["createdAt","updatedAt"],DbTable:["createdAt","updatedAt"],Endpoint:["createdAt","updatedAt"],DraftTable:["createdAt"],SyncState:["codeGraphSyncedAt","updatedAt"],AppSetting:["updatedAt"],ProjectMeta:["updatedAt"],CodeFile:["updatedAt"]}});UQ();import{existsSync as cZ}from"fs";import{homedir as lZ}from"os";import{join as r}from"path";function nZ(){return process.env.HOME||process.env.USERPROFILE||lZ()}var o=()=>r(nZ(),".claude"),jQ=()=>r(o(),"skills"),GQ=()=>r(o(),"settings.json"),NQ=()=>r(o(),"CLAUDE.md"),PQ="<!-- beacon:global:start -->",dQ="<!-- beacon:global:end -->";var dZ=k,KQ=[{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 aZ(Q,Z){return p(jQ(),Q,Z)}function aQ(Q){return T(jQ(),Q)}function sZ(Q){return c(jQ(),Q)}function tZ(Q){return L(GQ(),Q)}function rZ(Q){return _(GQ(),Q)}function oZ(Q){return S(GQ(),Q)}function iZ(Q){h(NQ(),PQ,dQ,Q)}function sQ(){return R(NQ(),PQ)}function eZ(){return m(NQ(),PQ,dQ)}function q1(){let Q={};for(let $ of j)Q[$]=aQ($);let Z={};for(let $ of KQ)Z[$.event]=rZ({event:$.event,command:$.command});return{homeExists:cZ(o()),skills:Q,hooks:Z,claudeMdBlock:sQ()}}async function Q0(){let{INIT_SKILL:Q,REFRESH_SKILL:Z,PLAN_SKILL:$,EXPLAIN_SKILL:J}=await Promise.resolve().then(() => (zQ(),VQ)),Y={"beacon-init":Q,"beacon-refresh":Z,"beacon-plan":$,"beacon-explain":J},V=[];for(let z of j){if(!aQ(z))V.push(z);aZ(z,Y[z])}let q=0;for(let z of KQ)if(tZ({event:z.event,matcher:z.matcher,command:z.command}))q++;let W=sQ();return iZ(dZ),{skillsAdded:V,hooksAdded:q,claudeMdBlockTouched:!W}}async function tQ(){if(AQ())return{ok:!0,skipped:"plugin",skillsAdded:[],hooksAdded:0,claudeMdBlockTouched:!1};let Q;if(IQ()){try{Z0()}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(() => (nQ(),lQ));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 Z0(){let Q=[];for(let J of j)if(sZ(J))Q.push(J);let Z=0;for(let J of KQ)if(oZ(J))Z++;let $=eZ();return{skillsRemoved:Q,hooksRemoved:Z,claudeMdBlockRemoved:$}}import{AsyncLocalStorage as j0}from"async_hooks";import{spawnSync as G0}from"child_process";import{createHash as N0}from"crypto";import{existsSync as QZ,mkdirSync as b,readFileSync as uQ,writeFileSync as MQ}from"fs";import{homedir as ZZ}from"os";import{basename as P0,join as G,parse as K0,resolve as eQ}from"path";function B(){return process.env.BEACON_HOME||G(ZZ(),".beacon")}function wQ(){return G(B(),"workspaces.json")}function u(Q){return N0("sha256").update(Q).digest("hex").slice(0,12)}function $Z(Q=process.cwd()){let Z=G0("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 JZ(Q){let Z=eQ(Q);return Z!==eQ(ZZ())&&Z!==K0(Z).root}function YZ(){return G(B(),"deleted.json")}function RQ(){try{let Q=JSON.parse(uQ(YZ(),"utf8"));return Array.isArray(Q)?Q:[]}catch{return[]}}function VZ(Q){b(B(),{recursive:!0}),MQ(YZ(),JSON.stringify(Q,null,2))}function zZ(Q){return RQ().includes(Q)}function u1(Q){let Z=RQ();if(!Z.includes(Q))VZ([...Z,Q])}function v0(Q){let Z=RQ();if(Z.includes(Q))VZ(Z.filter(($)=>$!==Q))}function e(Q){return G(B(),Q)}function C0(Q){return`file:${G(e(Q),"db.sqlite")}`}function f(){try{let Q=JSON.parse(uQ(wQ(),"utf8"));return Array.isArray(Q)?Q:[]}catch{return[]}}function TQ(Q){b(B(),{recursive:!0}),MQ(wQ(),JSON.stringify(Q,null,2))}function qZ(){return f().sort((Q,Z)=>Z.lastOpenedAt.localeCompare(Q.lastOpenedAt))}function P(Q){return f().find((Z)=>Z.id===Q)??null}function XZ(Q,Z,$=new Date().toISOString()){if(!JZ(Q))throw Error(`beacon: refusing to register a non-repo path as a workspace: ${Q}`);let J=u(Q);if(zZ(J))throw Error(`beacon: workspace ${J} (${Q}) was deleted \u2014 run \`beacon\` or /beacon-init to re-add it`);let Y=f(),V=Y.find((z)=>z.id===J),q={id:J,path:Q,name:Z||V?.name||P0(Q),lastOpenedAt:$},W=[q,...Y.filter((z)=>z.id!==J)];return b(e(J),{recursive:!0}),TQ(W),q}function M1(Q,Z){return v0(u(Q)),XZ(Q,Z)}function w1(Q,Z=new Date().toISOString()){let $=f(),J=$.find((Y)=>Y.id===Q);if(!J)return;J.lastOpenedAt=Z,TQ($)}function R1(Q){if(TQ(f().filter((Z)=>Z.id!==Q)),gQ()===Q)u0(qZ()[0]?.id??null)}function UZ(){return G(B(),"active")}function gQ(){try{return uQ(UZ(),"utf8").trim()||null}catch{return null}}function u0(Q){b(B(),{recursive:!0}),MQ(UZ(),Q??"")}function T1(){let Q=gQ();return Q?P(Q):null}function g1(){let Q=R0()??gQ();return Q?P(Q):null}function F1(Q){return P(Q)?.path??null}function O1(){return QZ(wQ())}var WZ="beacon_ws";function HZ(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&&P(Z))return Z;let $=HZ(Q,WZ);if($&&P($))return $;return M0()}function M0(){let Q=qZ();return Q.length===1?Q[0].id:null}var w0="x-beacon-workspace-path";async function f1(Q){let Z=Q.headers.get("x-beacon-workspace");if(Z&&P(Z))return Z;let $=Q.headers.get(w0);if($&&JZ($)&&!zZ(u($))&&(!Z||u($)===Z)){let Y=XZ($);return await T0(Y.id),Y.id}let J=HZ(Q,WZ);if(J&&P(J))return J;return null}var xZ=new j0;function D1(Q,Z){return Q?xZ.run(Q,Z):Z()}function R0(){return xZ.getStore()??null}var CQ=new Set;function A1(Q){CQ.delete(G(e(Q),"db.sqlite"))}async function T0(Q){let Z=e(Q),$=G(Z,"db.sqlite"),J=QZ($);if(J&&CQ.has($))return{ok:!0,created:!1,migrated:!1};try{b(Z,{recursive:!0});let{provisionDb:Y}=await iQ().then(() => oQ),V=await Y(C0(Q));return CQ.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)}}}import{connect as g0}from"net";var BZ=4319;function F0(Q,Z,$=400){return new Promise((J)=>{let Y=g0({host:Q,port:Z}),V=!1,q=(W)=>{if(V)return;V=!0,Y.destroy(),J(W)};Y.once("connect",()=>q(!0)),Y.once("error",()=>q(!1)),Y.setTimeout($,()=>q(!1))})}async function O0(Q){for(let Z of["127.0.0.1","::1"])if(await F0(Z,Q))return!1;return!0}async function y1(Q,Z=20){for(let $=Q;$<Q+Z;$++)if(await O0($))return $;return Q}import{resolve as b0}from"path";var f0="*** Begin Patch",D0=/^\*\*\* (Update File|Add File|Move to): (.+)$/;function A0(Q){let Z=[];for(let $ of Q.split(`
+`)){let J=D0.exec($.trim());if(!J)continue;let Y=J[2].trim();if(J[1]==="Move to")Z.pop();Z.push(Y)}return Z}function jZ(Q){let Z=Q.tool_input;if(Z===null||typeof Z!=="object")return[];let $=Z,J=[];if(typeof $.file_path==="string")J.push($.file_path);if(typeof $.path==="string")J.push($.path);if(Array.isArray($.files))for(let V of $.files){let q=V?.file_path;if(typeof q==="string")J.push(q)}if(J.length)return J;let Y=typeof Q.cwd==="string"?Q.cwd:process.cwd();for(let V of Object.values($)){if(typeof V!=="string"||!V.includes(f0))continue;return A0(V).map((q)=>b0(Y,q))}return[]}import{readFileSync as E0}from"fs";import{join as I0}from"path";function y0(){try{return JSON.parse(E0(I0(B(),"server.json"),"utf8"))}catch{return null}}function GZ(){if(process.env.BEACON_URL)return process.env.BEACON_URL;return`http://localhost:${y0()?.port||process.env.PORT||BZ}`}await tQ();var NZ="";for await(let Q of process.stdin)NZ+=Q;try{let Q=JSON.parse(NZ||"{}"),Z=jZ(Q);if(Z.length){let $=u($Z(typeof Q.cwd==="string"?Q.cwd:void 0));await fetch(`${GZ()}/api/map/touch-active`,{method:"POST",headers:{"content-type":"application/json","x-beacon-workspace":$},body:JSON.stringify({files:Z})}).catch(()=>{})}}catch{}process.exit(0);