trybeacon 0.1.34 → 0.1.35

package/.next/trace-build

@@ -1 +1 @@
-[{"name":"run-webpack","duration":27406623,"timestamp":57469586,"id":14,"parentId":1,"tags":{},"startTime":1781199932454,"traceId":"e34b2e31346c17a1"},{"name":"run-typescript","duration":11489459,"timestamp":84878997,"id":3966,"parentId":1,"tags":{},"startTime":1781199959864,"traceId":"e34b2e31346c17a1"},{"name":"static-check","duration":721435,"timestamp":96386659,"id":3969,"parentId":1,"tags":{},"startTime":1781199971372,"traceId":"e34b2e31346c17a1"},{"name":"static-generation","duration":3550410,"timestamp":98300615,"id":4109,"parentId":1,"tags":{},"startTime":1781199973286,"traceId":"e34b2e31346c17a1"},{"name":"collect-build-traces","duration":12089105,"timestamp":97110996,"id":4106,"parentId":1,"tags":{},"startTime":1781199972096,"traceId":"e34b2e31346c17a1"},{"name":"telemetry-flush","duration":52,"timestamp":109204187,"id":4118,"parentId":1,"tags":{},"startTime":1781199984189,"traceId":"e34b2e31346c17a1"},{"name":"next-build","duration":51869478,"timestamp":57334771,"id":1,"tags":{"buildMode":"default","version":"16.2.7","bundler":"webpack","has-custom-webpack-config":"false","use-build-worker":"true"},"startTime":1781199932320,"traceId":"e34b2e31346c17a1"}]
+[{"name":"run-webpack","duration":29275564,"timestamp":127503423,"id":14,"parentId":1,"tags":{},"startTime":1781205906327,"traceId":"9fc340e37337f1c7"},{"name":"run-typescript","duration":12093817,"timestamp":156781363,"id":3987,"parentId":1,"tags":{},"startTime":1781205935605,"traceId":"9fc340e37337f1c7"},{"name":"static-check","duration":744499,"timestamp":168895605,"id":3990,"parentId":1,"tags":{},"startTime":1781205947719,"traceId":"9fc340e37337f1c7"},{"name":"static-generation","duration":4215901,"timestamp":170631071,"id":4132,"parentId":1,"tags":{},"startTime":1781205949455,"traceId":"9fc340e37337f1c7"},{"name":"collect-build-traces","duration":13753910,"timestamp":169642981,"id":4129,"parentId":1,"tags":{},"startTime":1781205948467,"traceId":"9fc340e37337f1c7"},{"name":"telemetry-flush","duration":57,"timestamp":183400558,"id":4141,"parentId":1,"tags":{},"startTime":1781205962224,"traceId":"9fc340e37337f1c7"},{"name":"next-build","duration":56023131,"timestamp":127377495,"id":1,"tags":{"buildMode":"default","version":"16.2.7","bundler":"webpack","has-custom-webpack-config":"false","use-build-worker":"true"},"startTime":1781205906201,"traceId":"9fc340e37337f1c7"}]

package/.next/types/app/api/{plan → project-meta}/route.ts

@@ -1,10 +1,10 @@
-// File: /home/runner/work/beacon/beacon/app/api/plan/route.ts
-import * as entry from '../../../../../app/api/plan/route.js'
+// File: /home/runner/work/beacon/beacon/app/api/project-meta/route.ts
+import * as entry from '../../../../../app/api/project-meta/route.js'
 import type { NextRequest } from 'next/server.js'
 
 import type { InstantConfigForTypeCheckInternal } from 'next/dist/build/segment-config/app/app-segment-config.js'
 
-type TEntry = typeof import('../../../../../app/api/plan/route.js')
+type TEntry = typeof import('../../../../../app/api/project-meta/route.js')
 
 type SegmentParams<T extends Object = any> = T extends Record<string, any>
   ? { [K in keyof T]: T[K] extends string ? string | string[] | undefined : never }

package/.next/types/routes.d.ts

@@ -2,7 +2,7 @@
 // Do not edit this file manually
 
 type AppRoutes = "/" | "/docs" | "/feedback" | "/help" | "/map" | "/plan" | "/settings"
-type AppRouteHandlerRoutes = "/api/board-annotations" | "/api/board-annotations/[id]" | "/api/board-layout" | "/api/bug-flags" | "/api/bug-flags/[id]" | "/api/code-graph" | "/api/code-graph/position" | "/api/context" | "/api/context/feature" | "/api/context/file" | "/api/db/arrange" | "/api/db/backfill-access" | "/api/db/position" | "/api/db/prune-planned" | "/api/db/reconcile-endpoints" | "/api/db/relations/[id]" | "/api/db/tables/[id]" | "/api/draft" | "/api/draft/approve" | "/api/draft/status" | "/api/edges" | "/api/edges/[id]" | "/api/endpoints/[id]" | "/api/entities" | "/api/feedback" | "/api/feedback/[id]" | "/api/feedback/[id]/vote" | "/api/ingest" | "/api/init" | "/api/map" | "/api/map/describe" | "/api/map/files" | "/api/map/finish" | "/api/map/start" | "/api/map/touch-active" | "/api/nodes" | "/api/nodes/[id]" | "/api/nodes/[id]/position" | "/api/nodes/positions" | "/api/nodes/subtasks" | "/api/notes" | "/api/notes/[id]" | "/api/open" | "/api/plan" | "/api/plan/annotations" | "/api/plan/approve" | "/api/plan/history" | "/api/plan/markdown" | "/api/plan/presence" | "/api/plan/verdict" | "/api/preferences" | "/api/reset" | "/api/stream" | "/api/version" | "/api/workspace" | "/api/workspace/activate"
+type AppRouteHandlerRoutes = "/api/board-annotations" | "/api/board-annotations/[id]" | "/api/board-layout" | "/api/bug-flags" | "/api/bug-flags/[id]" | "/api/code-graph" | "/api/code-graph/position" | "/api/context" | "/api/context/feature" | "/api/context/file" | "/api/db/arrange" | "/api/db/backfill-access" | "/api/db/position" | "/api/db/prune-planned" | "/api/db/reconcile-endpoints" | "/api/db/relations/[id]" | "/api/db/tables/[id]" | "/api/draft" | "/api/draft/approve" | "/api/draft/status" | "/api/edges" | "/api/edges/[id]" | "/api/endpoints/[id]" | "/api/entities" | "/api/feedback" | "/api/feedback/[id]" | "/api/feedback/[id]/vote" | "/api/ingest" | "/api/init" | "/api/map" | "/api/map/describe" | "/api/map/files" | "/api/map/finish" | "/api/map/start" | "/api/map/touch-active" | "/api/nodes" | "/api/nodes/[id]" | "/api/nodes/[id]/position" | "/api/nodes/positions" | "/api/nodes/subtasks" | "/api/notes" | "/api/notes/[id]" | "/api/open" | "/api/plan" | "/api/plan/annotations" | "/api/plan/approve" | "/api/plan/history" | "/api/plan/markdown" | "/api/plan/presence" | "/api/plan/verdict" | "/api/preferences" | "/api/project-meta" | "/api/reset" | "/api/stream" | "/api/version" | "/api/workspace" | "/api/workspace/activate"
 type PageRoutes = never
 type LayoutRoutes = "/"
 type RedirectRoutes = never
@@ -63,6 +63,7 @@ interface ParamMap {
   "/api/plan/presence": {}
   "/api/plan/verdict": {}
   "/api/preferences": {}
+  "/api/project-meta": {}
   "/api/reset": {}
   "/api/stream": {}
   "/api/version": {}

package/.next/types/validator.ts

@@ -569,6 +569,15 @@ type RouteHandlerConfig<Route extends AppRouteHandlerRoutes = AppRouteHandlerRou
   type __Unused = __Check
 }
 
+// Validate ../../app/api/project-meta/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/project-meta">> = Specific
+  const handler = {} as typeof import("../../app/api/project-meta/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
 // Validate ../../app/api/reset/route.ts
 {
   type __IsExpected<Specific extends RouteHandlerConfig<"/api/reset">> = Specific

package/dist/bin/beacon.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env bun
 // @bun
-import{execSync as v,spawn as k}from"child_process";import{existsSync as S,mkdirSync as f,openSync as h,readFileSync as m,writeFileSync as g}from"fs";import{homedir as u,platform as w}from"os";import{basename as d,dirname as F,join as G}from"path";import{fileURLToPath as c}from"url";var P=F(c(import.meta.url)),L=d(F(P))==="dist",B=L?F(F(P)):F(P),O=process.cwd(),T=process.env.BEACON_HOME||G(u(),".beacon"),_=G(T,"server.json"),R=process.env.PORT||"4319";if(!process.env.BEACON_MIGRATIONS_DIR)process.env.BEACON_MIGRATIONS_DIR=G(B,"drizzle");function Q(z){if(!L)return G(B,z);return G(B,"dist",z.replace(/\.ts$/,".js"))}var $=process.argv[2];if($==="mcp")await import(Q("bin/mcp.ts"));else if($==="hook")await import(Q("bin/hook.ts"));else if($==="plan")await import(Q("bin/plan.ts"));else if($==="prompt")await import(Q("bin/prompt.ts"));else if($==="stop-hook")await import(Q("bin/stop-hook.ts"));else if($==="stop")i();else if($==="remove")await import(Q("bin/remove.ts"));else if($==="setup")await x(C()||O);else if($==="doctor")await import(Q("bin/doctor.ts"));else if($==="uninstall")await import(Q("bin/uninstall.ts"));else if($==="update")await s(process.argv.includes("--force")||process.argv.includes("-f"));else if($==="version"||$==="--version"||$==="-v")console.log(b());else await n();async function x(z,X=!1){let{installInitSkill:q,installRefreshSkill:J,installCodexRepoSkills:Y,ensureMcp:H,ensureWorkflowDoc:V}=await import(Q("lib/assets.ts")),{selfHealGlobal:I}=await import(Q("lib/global-install.ts")),{codexDetected:j}=await import(Q("lib/codex-install.ts")),M=await I(),K=q(z),U=J(z);V(z);let Z=H(z),y=j()?Y(z):[];if(X){if(Z.added)console.log(`[beacon] registered Beacon MCP in ${Z.path} \u2014 restart your agent CLI to use @beacon mentions.`)}else{console.log(`
+import{execSync as v,spawn as S}from"child_process";import{existsSync as f,mkdirSync as h,openSync as m,readFileSync as g,writeFileSync as u}from"fs";import{homedir as d,platform as w}from"os";import{basename as c,dirname as F,join as G}from"path";import{fileURLToPath as p}from"url";var P=F(p(import.meta.url)),L=c(F(P))==="dist",B=L?F(F(P)):F(P),O=process.cwd(),T=process.env.BEACON_HOME||G(d(),".beacon"),_=G(T,"server.json"),R=process.env.PORT||"4319";if(!process.env.BEACON_MIGRATIONS_DIR)process.env.BEACON_MIGRATIONS_DIR=G(B,"drizzle");function Q(z){if(!L)return G(B,z);return G(B,"dist",z.replace(/\.ts$/,".js"))}var $=process.argv[2];if($==="mcp")await import(Q("bin/mcp.ts"));else if($==="hook")await import(Q("bin/hook.ts"));else if($==="plan")await import(Q("bin/plan.ts"));else if($==="prompt")await import(Q("bin/prompt.ts"));else if($==="stop-hook")await import(Q("bin/stop-hook.ts"));else if($==="stop")k();else if($==="remove")await import(Q("bin/remove.ts"));else if($==="setup")await x(C()||O);else if($==="doctor")await import(Q("bin/doctor.ts"));else if($==="uninstall")await import(Q("bin/uninstall.ts"));else if($==="update")await i(process.argv.includes("--force")||process.argv.includes("-f"));else if($==="version"||$==="--version"||$==="-v")console.log(b());else await s();async function x(z,X=!1){let{installInitSkill:q,installRefreshSkill:J,installCodexRepoSkills:Y,ensureMcp:H,ensureWorkflowDoc:V}=await import(Q("lib/assets.ts")),{selfHealGlobal:I}=await import(Q("lib/global-install.ts")),{codexDetected:j}=await import(Q("lib/codex-install.ts")),M=await I(),K=q(z),U=J(z);V(z);let Z=H(z),y=j()?Y(z):[];if(X){if(Z.added)console.log(`[beacon] registered Beacon MCP in ${Z.path} \u2014 restart your agent CLI to use @beacon mentions.`)}else{console.log(`
   \u25C9 Beacon setup \xB7 ${z}`),console.log(`  \u2713 skill:  ${K}`),console.log(`  \u2713 skill:  ${U}`);for(let N of y)console.log(`  \u2713 skill:  ${N}`);console.log(`  ${Z.added?"\u2713 added ":"\xB7 kept  "} Beacon MCP in ${Z.path}`),console.log(`  \u2192 in this repo, run /beacon-init in your agent (Claude Code or Codex) to map the repo.
-`)}return{initSkill:K,refreshSkill:U,mcp:Z,codexSkills:y,heal:M}}function C(){try{return v("git rev-parse --show-toplevel",{cwd:O,stdio:["ignore","pipe","ignore"]}).toString().trim()}catch{return""}}function D(z){try{return process.kill(z,0),!0}catch{return!1}}function A(z){try{return JSON.parse(m(z,"utf8"))}catch{return null}}async function E(z){try{return(await fetch(z)).ok}catch{return!1}}async function p(z,X=60){for(let q=0;q<X;q++){if(await E(z))return!0;await new Promise((J)=>setTimeout(J,500))}return!1}function t(){f(T,{recursive:!0});let z=h(G(T,"server.log"),"a"),X={...process.env,PORT:R,BEACON_NO_OPEN:"1",BEACON_MIGRATIONS_DIR:G(B,"drizzle")};delete X.BEACON_REPO,delete X.BEACON_DATA_DIR,delete X.DATABASE_URL;let J=k("bun",L?["run","start"]:["run","dev"],{cwd:B,env:X,detached:!0,stdio:["ignore",z,z]});J.unref();let Y={pid:J.pid??0,port:R};return g(_,JSON.stringify(Y)),Y}async function a(){let z=A(_);if(z&&D(z.pid)&&await E(`http://localhost:${z.port}/api/workspace`))return z.port;console.log("[beacon] starting the Beacon server\u2026");let{port:X}=t();if(!await p(`http://localhost:${X}/api/workspace`))console.log("[beacon] (server is taking a while \u2014 it may still be compiling)");return X}function l(z){if(process.env.BEACON_NO_OPEN)return;let X=w()==="darwin"?"open":w()==="win32"?"start":"xdg-open";try{v(`${X} "${z}"`,{stdio:"ignore"})}catch{}}async function n(){let z=C()||O,{registerWorkspaceExplicit:X,idForPath:q,dataDirFor:J,ensureWorkspaceDb:Y,isRegistrableWorkspacePath:H}=await import(Q("lib/workspaces.ts"));if(!H(z))console.error(`[beacon] refusing to open Beacon in ${z} \u2014 that's your home directory, not a project.
-`+"          cd into a repo (or run `git init` there) and try again."),process.exit(1);let V=q(z),I=J(V),j=!S(G(I,"db.sqlite"));if(j)console.log(`[beacon] first run for ${z} \u2014 creating database\u2026`);let M=await Y(V);if(!M.ok)console.error(`[beacon] failed to provision database: ${M.error}`);if(j)console.log("[beacon] tip: already have code here? run `/beacon-init` in your agent (Claude Code or Codex) to map the project.");let{heal:K}=await x(z,!0),U=[];if(K.skillsAdded.length)U.push(`skills ${K.skillsAdded.join(", ")}`);if(K.hooksAdded)U.push(`${K.hooksAdded} Claude Code hook${K.hooksAdded===1?"":"s"}`);if(K.claudeMdBlockTouched)U.push("global CLAUDE.md block");if(U.length)console.log(`[beacon] wired into ~/.claude/: ${U.join(" + ")}.`);let Z=K.codex;if(Z){let W=[];if(Z.skillsAdded.length)W.push(`skills ${Z.skillsAdded.join(", ")}`);if(Z.hooksAdded)W.push(`${Z.hooksAdded} Codex hook${Z.hooksAdded===1?"":"s"}`);if(Z.agentsMdBlockTouched)W.push("global AGENTS.md block");if(Z.mcp.added)W.push("MCP entry in config.toml");if(W.length)console.log(`[beacon] wired into ~/.codex/: ${W.join(" + ")}.`);if(Z.mcp.error)console.log(`[beacon] codex MCP not wired: ${Z.mcp.error}`)}X(z);let y=await a(),N=`http://localhost:${y}/api/workspace/activate?id=${V}&redirect=/map`;console.log(`
+`)}return{initSkill:K,refreshSkill:U,mcp:Z,codexSkills:y,heal:M}}function C(){try{return v("git rev-parse --show-toplevel",{cwd:O,stdio:["ignore","pipe","ignore"]}).toString().trim()}catch{return""}}function E(z){try{return process.kill(z,0),!0}catch{return!1}}function A(z){try{return JSON.parse(g(z,"utf8"))}catch{return null}}async function D(z){try{return(await fetch(z)).ok}catch{return!1}}async function t(z,X=60){for(let q=0;q<X;q++){if(await D(z))return!0;await new Promise((J)=>setTimeout(J,500))}return!1}function a(){h(T,{recursive:!0});let z=m(G(T,"server.log"),"a"),X={...process.env,PORT:R,BEACON_NO_OPEN:"1",BEACON_MIGRATIONS_DIR:G(B,"drizzle")};delete X.BEACON_REPO,delete X.BEACON_DATA_DIR,delete X.DATABASE_URL;let J=S("bun",L?["run","start"]:["run","dev"],{cwd:B,env:X,detached:!0,stdio:["ignore",z,z]});J.unref();let Y={pid:J.pid??0,port:R};return u(_,JSON.stringify(Y)),Y}async function l(){let z=A(_);if(z&&E(z.pid)&&await D(`http://localhost:${z.port}/api/workspace`))return z.port;console.log("[beacon] starting the Beacon server\u2026");let{port:X}=a();if(!await t(`http://localhost:${X}/api/workspace`))console.log("[beacon] (server is taking a while \u2014 it may still be compiling)");return X}function n(z){if(process.env.BEACON_NO_OPEN)return;let X=w()==="darwin"?"open":w()==="win32"?"start":"xdg-open";try{v(`${X} "${z}"`,{stdio:"ignore"})}catch{}}async function s(){let z=C()||O,{registerWorkspaceExplicit:X,idForPath:q,dataDirFor:J,ensureWorkspaceDb:Y,isRegistrableWorkspacePath:H}=await import(Q("lib/workspaces.ts"));if(!H(z))console.error(`[beacon] refusing to open Beacon in ${z} \u2014 that's your home directory, not a project.
+`+"          cd into a repo (or run `git init` there) and try again."),process.exit(1);let V=q(z),I=J(V),j=!f(G(I,"db.sqlite"));if(j)console.log(`[beacon] first run for ${z} \u2014 creating database\u2026`);let M=await Y(V);if(!M.ok)console.error(`[beacon] failed to provision database: ${M.error}`);if(j)console.log("[beacon] tip: already have code here? run `/beacon-init` in your agent (Claude Code or Codex) to map the project.");let{heal:K}=await x(z,!0),U=[];if(K.skillsAdded.length)U.push(`skills ${K.skillsAdded.join(", ")}`);if(K.hooksAdded)U.push(`${K.hooksAdded} Claude Code hook${K.hooksAdded===1?"":"s"}`);if(K.claudeMdBlockTouched)U.push("global CLAUDE.md block");if(U.length)console.log(`[beacon] wired into ~/.claude/: ${U.join(" + ")}.`);let Z=K.codex;if(Z){let W=[];if(Z.skillsAdded.length)W.push(`skills ${Z.skillsAdded.join(", ")}`);if(Z.hooksAdded)W.push(`${Z.hooksAdded} Codex hook${Z.hooksAdded===1?"":"s"}`);if(Z.agentsMdBlockTouched)W.push("global AGENTS.md block");if(Z.mcp.added)W.push("MCP entry in config.toml");if(W.length)console.log(`[beacon] wired into ~/.codex/: ${W.join(" + ")}.`);if(Z.mcp.error)console.log(`[beacon] codex MCP not wired: ${Z.mcp.error}`)}X(z);let y=await l(),N=`http://localhost:${y}/api/workspace/activate?id=${V}&redirect=/map`;console.log(`
   \u25C9 Beacon
   repo:  ${z}
   data:  ${I}
   url:   http://localhost:${y}
-`),console.log("  (the server keeps running in the background \u2014 `beacon stop` to stop it)\n"),l(N)}function b(){return A(G(B,"package.json"))?.version??"0.0.0"}async function s(z){let X=b(),{INSTALL_COMMAND:q,NPM_LATEST_URL:J}=await import(Q("lib/release.ts"));if(w()==="win32"){console.log(`[beacon] current version v${X}.`),console.log(`[beacon] on Windows, update with your package manager:
+`),console.log("  (the server keeps running in the background \u2014 `beacon stop` to stop it)\n"),n(N)}function b(){return A(G(B,"package.json"))?.version??"0.0.0"}async function i(z){let X=b(),{INSTALL_COMMAND:q,NPM_LATEST_URL:J}=await import(Q("lib/release.ts"));if(w()==="win32"){console.log(`[beacon] current version v${X}.`),console.log(`[beacon] on Windows, update with your package manager:
   npm i -g trybeacon@latest`);return}let Y=null;try{let H=await fetch(J);if(H.ok)Y=(await H.json()).version??null}catch{}if(Y&&!z){let{isNewerVersion:H}=await import(Q("lib/semver.ts"));if(!H(Y,X)){console.log(`[beacon] already on the latest version (v${X}).`),console.log("         run `beacon update --force` to reinstall anyway.");return}}console.log(Y?`[beacon] updating Beacon v${X} \u2192 v${Y}\u2026`:`[beacon] reinstalling Beacon (current v${X})\u2026`);try{v(q,{stdio:"inherit"})}catch{console.error(`[beacon] update failed. Run it manually:
-  ${q}`),process.exitCode=1;return}console.log("[beacon] updated. Restart the daemon to run the new version: `beacon stop` then `beacon`.")}function i(){let z=A(_);if(z&&D(z.pid))try{try{process.kill(-z.pid)}catch{process.kill(z.pid)}console.log(`[beacon] stopped the server (pid ${z.pid}).`)}catch{console.log("[beacon] could not stop the server.")}else console.log("[beacon] no server running.")}
+  ${q}`),process.exitCode=1;return}k(),console.log("[beacon] updated. Run `beacon` to relaunch on the new version.")}function k(){let z=A(_);if(z&&E(z.pid))try{try{process.kill(-z.pid)}catch{process.kill(z.pid)}console.log(`[beacon] stopped the server (pid ${z.pid}).`)}catch{console.log("[beacon] could not stop the server.")}else console.log("[beacon] no server running.")}

package/dist/bin/doctor.js

@@ -28,8 +28,9 @@ The user already has Beacon running. You're going to map this repository's archi
 
 A single \`beacon_init_persist\` MCP tool call with:
 
-- **components**: 8\u201325 main building blocks of this codebase. NOT every file. Group them by \`domain\` (short UPPERCASE: AUTH, API, DATA, UI, JOBS, INFRA, BILLING, SEARCH, \u2026). For each: a one-line technical \`role\`, a one-sentence plain-language \`plain\`, the few \`files\` that implement it (repo-relative), and \`depends\` listing other component titles it relies on. Use the dependency graph you can see in the source \u2014 files that import each other heavily usually belong together. If you spot a bug or something worth investigating while reading a component's code, add \`bugs: [{ note }]\` to that component \u2014 it renders as a bug flag on the node (attributed to the agent). Only flag what you actually saw in the code; don't speculate.
-- **roadmap**: 3\u20136 BROAD strategic directions. Big-picture themes only \u2014 "Harden auth & security", "Add observability", "Scale the data layer", "Pay down test-coverage debt". NOT detailed tasks. NOT file-level. Each gets a short title and one-line \`why\`. If one of them is a concrete BUG to fix (something broken you saw in the code), add \`kind: "BUG"\` so it renders as a typed bug card.
+- **hasFrontend**: \`true\` or \`false\` \u2014 does this repo have a frontend surface (UI code)? You just read the repo, so you know. Set it explicitly; it gates the frontend/backend \`layer\` distinction on the boards (a pure-backend repo never shows it).
+- **components**: 8\u201325 main building blocks of this codebase. NOT every file. Group them by \`domain\` (short UPPERCASE: AUTH, API, DATA, UI, JOBS, INFRA, BILLING, SEARCH, \u2026). For each: a one-line technical \`role\`, a one-sentence plain-language \`plain\`, the few \`files\` that implement it (repo-relative), \`depends\` listing other component titles it relies on \u2014 and, when \`hasFrontend\` is true, \`layer\` (\`"frontend" | "backend" | "fullstack"\`). Use the dependency graph you can see in the source \u2014 files that import each other heavily usually belong together. If you spot a bug or something worth investigating while reading a component's code, add \`bugs: [{ note }]\` to that component \u2014 it renders as a bug flag on the node (attributed to the agent). Only flag what you actually saw in the code; don't speculate.
+- **roadmap**: 3\u20136 BROAD strategic directions. Big-picture themes only \u2014 "Harden auth & security", "Add observability", "Scale the data layer", "Pay down test-coverage debt". NOT detailed tasks. NOT file-level. Each gets a short title and one-line \`why\`. If one of them is a concrete BUG to fix (something broken you saw in the code), add \`kind: "BUG"\` so it renders as a typed bug card. When \`hasFrontend\` is true, give each a \`layer\` too (\`"frontend" | "backend" | "fullstack"\`).
 - **overview**: one paragraph describing what this project is and its stack. This lands in AGENTS.md as the project intro.
 - **conventions**: 3\u20138 concrete rules a contributor MUST follow \u2014 build/test commands, where code goes, patterns, things easy to get wrong. Infer from actual files, not assumptions.
 - **snapshot** (optional but encouraged): \`{ tables, relations, endpoints }\` for the existing database. If the project uses Prisma, read \`prisma/schema.prisma\`. If SQLAlchemy, read the model files. If Django, read \`models.py\`. If you find no obvious schema source, skip the snapshot \u2014 don't fabricate.
@@ -87,7 +88,7 @@ The one caveat: if the user manually edited an INIT-source node on the canvas (e
    - **~ changed**: COMPONENT_X (role expanded to cover Y)
    - **schema**: + 2 new tables (TableA, TableB); + 3 new endpoints; \u2212 1 deprecated endpoint
    No need to wait for confirmation \u2014 just show the diff so the user sees what's about to land.
-5. **Call \`beacon_init_persist\`** ONCE with the refreshed full analysis (same shape as init: \`components\`, \`roadmap\`, \`overview\`, \`conventions\`, \`snapshot\`). It replaces all init-source nodes and regenerates \`AGENTS.md\`. Bug flags already on a component survive the refresh (they're carried over by title); add \`bugs: [{ note }]\` for anything NEW you found worth investigating \u2014 identical open flags are not duplicated.
+5. **Call \`beacon_init_persist\`** ONCE with the refreshed full analysis (same shape as init: \`components\`, \`roadmap\`, \`overview\`, \`conventions\`, \`snapshot\`, \`hasFrontend\` \u2014 re-assert it, the stack may have changed). It replaces all init-source nodes and regenerates \`AGENTS.md\`. Bug flags already on a component survive the refresh (they're carried over by title); add \`bugs: [{ note }]\` for anything NEW you found worth investigating \u2014 identical open flags are not duplicated.
 
 ## What you should NOT do
 
@@ -166,6 +167,8 @@ When listing endpoints, give each \`uses: [{ table, access }]\` so the endpoint\
 
 EVERY feature MUST carry \`category\` (e.g. AUTH | SEARCH | DATA | INTEL | BILLING | \u2026; \`cluster\` is accepted as an alias) and \`priority\` (0 = P0 critical, 1 = P1 high, 2 = P2 medium, 3 = P3 low). Beacon REJECTS a plan whose features omit either \u2014 \`beacon_propose_plan\` returns the list of what's missing, and an ExitPlanMode \`\`\`beacon block is denied \u2014 so set both on every feature instead of relying on defaults.
 
+When the workspace HAS A FRONTEND (Beacon knows \u2014 the agent set \`hasFrontend\` at init, or frontend files were detected), every feature must ALSO carry \`layer\`: \`"frontend" | "backend" | "fullstack"\` \u2014 which side of the stack the work lands on. Plans omitting it are REJECTED the same way category/priority are. It works on every surface that creates roadmap cards (\`beacon_propose_plan\`, the \`\`\`beacon block, \`beacon_start_feature\`, \`beacon_add_subtasks\` \u2014 sub-tasks default to the parent's layer) and on architecture components (\`beacon_describe_feature\` / \`beacon_init_persist\`). In a pure-backend repo, never set it \u2014 the boards don't show it there.
+
 REUSE before you create. Call \`beacon_map\` to see the features + categories that already exist. Beacon HARD-BLOCKS a feature that duplicates an existing one (it returns the existing feature to use instead) and one created without a category \u2014 so don't re-create work that's already on the board, and reuse an existing category rather than a near-synonym. \`category\` is the ONLY domain field. \`front\` (in \`beacon_start_feature\`) nests a feature UNDER an existing parent feature \u2014 it is NOT a domain tag; a \`front\` that matches no real feature is rejected.
 
 When listing features, give each \`dependsOn: ["Other feature title", \u2026]\` for any feature that must ship after another in the same plan. Beacon draws these as "depends on" links so the roadmap shows the dependency chain instead of loose, disconnected cards.

package/dist/bin/hook.js

@@ -28,8 +28,9 @@ The user already has Beacon running. You're going to map this repository's archi
 
 A single \`beacon_init_persist\` MCP tool call with:
 
-- **components**: 8\u201325 main building blocks of this codebase. NOT every file. Group them by \`domain\` (short UPPERCASE: AUTH, API, DATA, UI, JOBS, INFRA, BILLING, SEARCH, \u2026). For each: a one-line technical \`role\`, a one-sentence plain-language \`plain\`, the few \`files\` that implement it (repo-relative), and \`depends\` listing other component titles it relies on. Use the dependency graph you can see in the source \u2014 files that import each other heavily usually belong together. If you spot a bug or something worth investigating while reading a component's code, add \`bugs: [{ note }]\` to that component \u2014 it renders as a bug flag on the node (attributed to the agent). Only flag what you actually saw in the code; don't speculate.
-- **roadmap**: 3\u20136 BROAD strategic directions. Big-picture themes only \u2014 "Harden auth & security", "Add observability", "Scale the data layer", "Pay down test-coverage debt". NOT detailed tasks. NOT file-level. Each gets a short title and one-line \`why\`. If one of them is a concrete BUG to fix (something broken you saw in the code), add \`kind: "BUG"\` so it renders as a typed bug card.
+- **hasFrontend**: \`true\` or \`false\` \u2014 does this repo have a frontend surface (UI code)? You just read the repo, so you know. Set it explicitly; it gates the frontend/backend \`layer\` distinction on the boards (a pure-backend repo never shows it).
+- **components**: 8\u201325 main building blocks of this codebase. NOT every file. Group them by \`domain\` (short UPPERCASE: AUTH, API, DATA, UI, JOBS, INFRA, BILLING, SEARCH, \u2026). For each: a one-line technical \`role\`, a one-sentence plain-language \`plain\`, the few \`files\` that implement it (repo-relative), \`depends\` listing other component titles it relies on \u2014 and, when \`hasFrontend\` is true, \`layer\` (\`"frontend" | "backend" | "fullstack"\`). Use the dependency graph you can see in the source \u2014 files that import each other heavily usually belong together. If you spot a bug or something worth investigating while reading a component's code, add \`bugs: [{ note }]\` to that component \u2014 it renders as a bug flag on the node (attributed to the agent). Only flag what you actually saw in the code; don't speculate.
+- **roadmap**: 3\u20136 BROAD strategic directions. Big-picture themes only \u2014 "Harden auth & security", "Add observability", "Scale the data layer", "Pay down test-coverage debt". NOT detailed tasks. NOT file-level. Each gets a short title and one-line \`why\`. If one of them is a concrete BUG to fix (something broken you saw in the code), add \`kind: "BUG"\` so it renders as a typed bug card. When \`hasFrontend\` is true, give each a \`layer\` too (\`"frontend" | "backend" | "fullstack"\`).
 - **overview**: one paragraph describing what this project is and its stack. This lands in AGENTS.md as the project intro.
 - **conventions**: 3\u20138 concrete rules a contributor MUST follow \u2014 build/test commands, where code goes, patterns, things easy to get wrong. Infer from actual files, not assumptions.
 - **snapshot** (optional but encouraged): \`{ tables, relations, endpoints }\` for the existing database. If the project uses Prisma, read \`prisma/schema.prisma\`. If SQLAlchemy, read the model files. If Django, read \`models.py\`. If you find no obvious schema source, skip the snapshot \u2014 don't fabricate.
@@ -87,7 +88,7 @@ The one caveat: if the user manually edited an INIT-source node on the canvas (e
    - **~ changed**: COMPONENT_X (role expanded to cover Y)
    - **schema**: + 2 new tables (TableA, TableB); + 3 new endpoints; \u2212 1 deprecated endpoint
    No need to wait for confirmation \u2014 just show the diff so the user sees what's about to land.
-5. **Call \`beacon_init_persist\`** ONCE with the refreshed full analysis (same shape as init: \`components\`, \`roadmap\`, \`overview\`, \`conventions\`, \`snapshot\`). It replaces all init-source nodes and regenerates \`AGENTS.md\`. Bug flags already on a component survive the refresh (they're carried over by title); add \`bugs: [{ note }]\` for anything NEW you found worth investigating \u2014 identical open flags are not duplicated.
+5. **Call \`beacon_init_persist\`** ONCE with the refreshed full analysis (same shape as init: \`components\`, \`roadmap\`, \`overview\`, \`conventions\`, \`snapshot\`, \`hasFrontend\` \u2014 re-assert it, the stack may have changed). It replaces all init-source nodes and regenerates \`AGENTS.md\`. Bug flags already on a component survive the refresh (they're carried over by title); add \`bugs: [{ note }]\` for anything NEW you found worth investigating \u2014 identical open flags are not duplicated.
 
 ## What you should NOT do
 
@@ -166,6 +167,8 @@ When listing endpoints, give each \`uses: [{ table, access }]\` so the endpoint\
 
 EVERY feature MUST carry \`category\` (e.g. AUTH | SEARCH | DATA | INTEL | BILLING | \u2026; \`cluster\` is accepted as an alias) and \`priority\` (0 = P0 critical, 1 = P1 high, 2 = P2 medium, 3 = P3 low). Beacon REJECTS a plan whose features omit either \u2014 \`beacon_propose_plan\` returns the list of what's missing, and an ExitPlanMode \`\`\`beacon block is denied \u2014 so set both on every feature instead of relying on defaults.
 
+When the workspace HAS A FRONTEND (Beacon knows \u2014 the agent set \`hasFrontend\` at init, or frontend files were detected), every feature must ALSO carry \`layer\`: \`"frontend" | "backend" | "fullstack"\` \u2014 which side of the stack the work lands on. Plans omitting it are REJECTED the same way category/priority are. It works on every surface that creates roadmap cards (\`beacon_propose_plan\`, the \`\`\`beacon block, \`beacon_start_feature\`, \`beacon_add_subtasks\` \u2014 sub-tasks default to the parent's layer) and on architecture components (\`beacon_describe_feature\` / \`beacon_init_persist\`). In a pure-backend repo, never set it \u2014 the boards don't show it there.
+
 REUSE before you create. Call \`beacon_map\` to see the features + categories that already exist. Beacon HARD-BLOCKS a feature that duplicates an existing one (it returns the existing feature to use instead) and one created without a category \u2014 so don't re-create work that's already on the board, and reuse an existing category rather than a near-synonym. \`category\` is the ONLY domain field. \`front\` (in \`beacon_start_feature\`) nests a feature UNDER an existing parent feature \u2014 it is NOT a domain tag; a \`front\` that matches no real feature is rejected.
 
 When listing features, give each \`dependsOn: ["Other feature title", \u2026]\` for any feature that must ship after another in the same plan. Beacon draws these as "depends on" links so the roadmap shows the dependency chain instead of loose, disconnected cards.