arkaik 0.1.0 → 0.1.2

package/dist/assets/skill/scripts/validate-bundle.js

@@ -10,9 +10,9 @@
  *
  * Usage: node validate-bundle.js <path-to-bundle.json>
  */
-"use strict";var P=require("node:fs"),B=require("node:path");var G=["flow","view","data-model","api-endpoint","acceptance"],C=["idea","backlog","prioritized","development","releasing","live","archived","blocked"],q=["web","ios","android"],K=["composes","calls","displays","queries","covers"];var Q=["saves-time","simplifies","makes-money","reduces-risk","organizes","integrates","connects","reduces-effort","avoids-hassles","reduces-cost","quality","variety","sensory-appeal","informs","reduces-anxiety","rewards-me","nostalgia","design-aesthetics","badge-value","wellness","therapeutic-value","fun-entertainment","attractiveness","provides-access","provides-hope","self-actualization","motivation","heirloom","affiliation-belonging","self-transcendence"];var Z={flow:"F-",view:"V-","data-model":"DM-","api-endpoint":"API-",acceptance:"AC-"};function de(f){let a=e=>typeof e=="string"?e:"";return[...f].sort((e,r)=>{let $=a(e.ts),v=a(r.ts);if($<v)return-1;if($>v)return 1;let p=a(e.id),y=a(r.id);return p<y?-1:p>y?1:0})}function ee(f){let a=[],e=[];return f.split(/\r?\n/).forEach(($,v)=>{let p=v+1;if($.trim()==="")return;let y;try{y=JSON.parse($)}catch(h){e.push({line:p,rule:"journal-line-parse",message:`Line ${p}: not valid JSON \u2014 ${h.message}`,severity:"error"});return}if(typeof y!="object"||y===null||Array.isArray(y)){e.push({line:p,rule:"journal-line-shape",message:`Line ${p}: each journal line must be a single JSON event object.`,severity:"error"});return}let _=y,E=[];if(typeof _.id!="string"&&E.push("id"),typeof _.ts!="string"&&E.push("ts"),typeof _.type!="string"&&E.push("type"),E.length>0){e.push({line:p,rule:"journal-line-shape",message:`Line ${p}: event is missing required envelope field(s): ${E.join(", ")}.`,severity:"error"});return}a.push(_)}),{events:a,findings:e}}var ce={"node.updated":["node_id"],"node.status_changed":["node_id"],"node.deleted":["node_id"],"edge.added":["source_id","target_id"],"ref.added":["node_id"],"ref.removed":["node_id"],"ref.status_changed":["node_id"],"idea.proposed":["node_id"],"request.filed":["node_id"]};function te(f){let a=[],e=f.journal;if(e===void 0)return a;if(!Array.isArray(e))return a.push({path:"journal",rule:"journal-shape",message:"journal must be an array of events when present.",severity:"error"}),a;if(e.length===0)return a;let r=o=>typeof o=="string"?o:void 0,$=Array.isArray(f.nodes)?f.nodes:[],v=Array.isArray(f.edges)?f.edges:[],p=new Map;for(let o of $){let d=r(o?.id);d!==void 0&&p.set(d,o.status)}let y=new Set;for(let o of v){let d=r(o?.id);d!==void 0&&y.add(d)}let _=[];e.forEach((o,d)=>{let w=`journal[${d}]`;if(typeof o!="object"||o===null||Array.isArray(o)){a.push({path:w,rule:"journal-event-shape",message:`journal[${d}]: each event must be a JSON object.`,severity:"error"});return}let S=o,j=[];if(r(S.id)===void 0&&j.push("id"),r(S.ts)===void 0&&j.push("ts"),r(S.type)===void 0&&j.push("type"),j.length>0){a.push({path:w,rule:"journal-event-envelope",message:`journal[${d}]: event is missing required envelope field(s): ${j.join(", ")}.`,severity:"error"});return}_.push({ev:S,index:d})});let E=new Set(p.keys()),h=new Set(y);for(let{ev:o}of _)if(o.type==="node.created"){let d=r(o.node_id);d&&E.add(d)}else if(o.type==="edge.added"){let d=r(o.edge_id);d&&h.add(d)}let R=de(_.map(o=>o.ev)),I=new Set,b=new Map;for(let o of R)if(o.type==="node.created"){let d=r(o.node_id);d&&I.add(d)}else if(o.type==="node.status_changed"){let d=r(o.node_id);if(d&&o.platform===void 0){let w=r(o.to);w!==void 0&&b.set(d,w)}}for(let{ev:o,index:d}of _){let w=ce[o.type];if(w)for(let S of w){let j=r(o[S]);j!==void 0&&!E.has(j)&&a.push({path:`journal[${d}].${S}`,rule:"journal-dangling-node-ref",message:`journal[${d}] (${o.type}): references node "${j}" that never existed in the snapshot or journal.`,severity:"error"})}if(o.type==="edge.removed"){let S=r(o.edge_id);S!==void 0&&!h.has(S)&&a.push({path:`journal[${d}].edge_id`,rule:"journal-dangling-edge-ref",message:`journal[${d}] (edge.removed): references edge "${S}" that never existed in the snapshot or journal.`,severity:"error"})}}for(let[o,d]of p){I.has(o)||a.push({path:"journal",rule:"journal-missing-node-created",message:`Node "${o}" is present in the snapshot but has no node.created event in the journal.`,severity:"error"});let w=b.get(o);w!==void 0&&w!==d&&a.push({path:"journal",rule:"journal-status-mismatch",message:`Node "${o}": journal's last node.status_changed.to "${w}" disagrees with snapshot status "${String(d)}".`,severity:"error"})}return a}var le=["journey","system"];function ne(f){return le.includes(f)}var pe=["beta","monitoring","deprecated"],se=["compact","large"],ie=2*1024*1024;function fe(f){let a=f.indexOf(",");if(a===-1)return 0;let e=f.slice(a+1),r=e.endsWith("==")?2:e.endsWith("=")?1:0;return Math.floor(e.length*3/4)-r}var ue={composes:[["flow","view"],["flow","flow"],["view","flow"],["view","view"]],calls:[["view","api-endpoint"],["flow","api-endpoint"],["api-endpoint","api-endpoint"]],displays:[["view","data-model"]],queries:[["api-endpoint","data-model"]],covers:[["acceptance","view"],["acceptance","flow"]]};function oe(f){return typeof f=="string"&&!Number.isNaN(Date.parse(f))}function re(f){let a=[],e=(s,u,n)=>a.push({path:s,rule:u,message:n,severity:"error"}),r=(s,u,n)=>a.push({path:s,rule:u,message:n,severity:"warning"}),$=()=>{let s=a.filter(n=>n.severity==="error"),u=a.filter(n=>n.severity==="warning");return{valid:s.length===0,findings:a,errors:s,warnings:u}};if(typeof f!="object"||f===null||Array.isArray(f))return e("","bundle-shape","Bundle must be an object with project, nodes, and edges."),$();let v=f,p=v.project,y=v.nodes,_=v.edges;if(!p||!y||!_)return e("","bundle-shape","Missing top-level keys (project, nodes, edges)."),$();if(!Array.isArray(y))return e("nodes","bundle-shape","nodes must be an array."),$();if(!Array.isArray(_))return e("edges","bundle-shape","edges must be an array."),$();let E=y,h=_,R=new Map,I=new Set;p.id||e("project.id","project-id-required","project.id is missing"),(typeof p.title!="string"||!p.title.trim())&&e("project.title","title-non-empty","project.title is missing or empty"),p.created_at||e("project.created_at","timestamp-required","project.created_at is missing"),p.updated_at||e("project.updated_at","timestamp-required","project.updated_at is missing"),p.created_at&&!oe(p.created_at)&&r("project.created_at","iso-timestamp","project.created_at is not a valid ISO 8601 timestamp"),p.updated_at&&!oe(p.updated_at)&&r("project.updated_at","iso-timestamp","project.updated_at is not a valid ISO 8601 timestamp");let b=p.metadata;b&&b.view_card_variant!==void 0&&!se.includes(b.view_card_variant)&&e("project.metadata.view_card_variant","view-card-variant",`project.metadata.view_card_variant must be one of ${se.join(", ")} (import rejects other values)`),E.forEach((s,u)=>{let n=`nodes[${u}]`,t=s.id;I.has(t)&&e(`${n}.id`,"duplicate-node-id",`Duplicate node ID: ${t}`),I.add(t),R.set(t,s),(typeof s.title!="string"||!s.title.trim())&&e(`${n}.title`,"title-non-empty",`Node ${t}: title is missing or empty`);let c=s.species,i=Z[c];i&&!(typeof t=="string"&&t.startsWith(i))&&e(`${n}.id`,"species-prefix",`Node ${t}: species "${c}" should have prefix "${i}"`),G.includes(c)||e(`${n}.species`,"valid-species",`Node ${t}: invalid species "${c}"`),s.project_id!==p.id&&e(`${n}.project_id`,"project-id-match",`Node ${t}: project_id "${s.project_id}" does not match project.id "${p.id}"`),C.includes(s.status)||e(`${n}.status`,"valid-status",`Node ${t}: invalid status "${s.status}"`);let m=s.platforms;if(!m||m.length===0)e(`${n}.platforms`,"platforms-non-empty",`Node ${t}: platforms array is empty or missing`);else for(let g of m)q.includes(g)||e(`${n}.platforms`,"valid-platform",`Node ${t}: invalid platform "${g}"`);let l=s.metadata||{};l.stage!==void 0&&!pe.includes(l.stage)&&e(`${n}.metadata.stage`,"valid-stage",`Node ${t}: invalid metadata.stage "${l.stage}"`);let x=l.platformNotes;if(x)for(let g of Object.keys(x))q.includes(g)||e(`${n}.metadata.platformNotes`,"valid-platform",`Node ${t}: platformNotes has invalid platform "${g}"`);let N=l.platformStatuses;if(N)for(let[g,A]of Object.entries(N))q.includes(g)?Array.isArray(m)&&!m.includes(g)&&r(`${n}.metadata.platformStatuses`,"platform-statuses-subset",`Node ${t}: platformStatuses covers platform "${g}" not in node.platforms`):e(`${n}.metadata.platformStatuses`,"valid-platform",`Node ${t}: platformStatuses has invalid platform "${g}"`),C.includes(A)||e(`${n}.metadata.platformStatuses`,"valid-status",`Node ${t}: platformStatuses has invalid status "${A}" for platform "${g}"`);let D=l.platformScreenshots;if(D){for(let[g,A]of Object.entries(D))if(typeof A=="string"&&A.startsWith("data:")){let O=fe(A);O>ie&&r(`${n}.metadata.platformScreenshots`,"screenshot-data-uri-size",`Node ${t}: platformScreenshots.${g} is a ${(O/(1024*1024)).toFixed(1)}MB data URI, above the ${ie/(1024*1024)}MB guidance (docs/spec/bundle-format.md \xA7 Asset Values) \u2014 consider a relative path or hosted URL instead`)}}let T=l.gherkin,M=l.values;if(c==="acceptance"?((typeof T!="string"||!T.trim())&&r(`${n}.metadata.gherkin`,"acceptance-gherkin-missing",`Acceptance ${t}: metadata.gherkin is missing or empty (one Given/When/Then scenario expected)`),(!Array.isArray(M)||M.length===0)&&r(`${n}.metadata.values`,"acceptance-values-missing",`Acceptance ${t}: metadata.values is missing or empty (assign 1-3 value elements)`)):(T!==void 0&&r(`${n}.metadata.gherkin`,"gherkin-species",`Node ${t}: metadata.gherkin is only meaningful on acceptance nodes`),M!==void 0&&r(`${n}.metadata.values`,"values-species",`Node ${t}: metadata.values is only meaningful on acceptance nodes`)),Array.isArray(M))for(let g of M)Q.includes(g)||e(`${n}.metadata.values`,"valid-value",`Node ${t}: invalid value element "${g}"`);let V=l.refs;if(Array.isArray(V)){let g=new Set;V.forEach((A,O)=>{let J=A??{},U=`${n}.metadata.refs[${O}]`,k=J.id;typeof k!="string"||!k.trim()?e(`${U}.id`,"ref-id-required",`Node ${t}: ref is missing an id`):g.has(k)?e(`${U}.id`,"duplicate-ref-id",`Node ${t}: duplicate ref id "${k}"`):g.add(k),(typeof J.url!="string"||!J.url.trim())&&e(`${U}.url`,"ref-url-required",`Node ${t}: ref "${k}" is missing a url`),J.status_mapped!==void 0&&!C.includes(J.status_mapped)&&e(`${U}.status_mapped`,"valid-status",`Node ${t}: ref "${k}" has invalid status_mapped "${J.status_mapped}"`)})}if(c==="flow"){let g=l.playlist;!s.metadata||!g||!g.entries?e(`${n}.metadata.playlist`,"flow-playlist-required",`Flow ${t}: missing metadata.playlist.entries`):g.entries.length===0&&r(`${n}.metadata.playlist`,"flow-playlist-empty",`Flow ${t}: playlist is empty`)}});let o=p.root_node_id;o&&!I.has(o)&&e("project.root_node_id","root-node-exists",`project.root_node_id "${o}" does not reference an existing node`);let d=b?.maps;if(Array.isArray(d)){let s=new Set;d.forEach((u,n)=>{if(typeof u!="object"||u===null||Array.isArray(u))return;let t=u,c=`project.metadata.maps[${n}]`,i=typeof t.id=="string"?t.id:void 0;i!==void 0&&(s.has(i)&&r(`${c}.id`,"map-duplicate-id",`Duplicate map id "${i}"`),s.add(i),ne(i)&&r(`${c}.id`,"map-shadows-built-in",`Map id "${i}" shadows a built-in map and will be ignored`));let m=t.root_node_id;typeof m=="string"&&!I.has(m)&&r(`${c}.root_node_id`,"map-unknown-root",`Map "${i??n}" anchors on "${m}" which does not reference an existing node`),Array.isArray(t.species)&&t.species.forEach((l,x)=>{typeof l=="string"&&!G.includes(l)&&r(`${c}.species[${x}]`,"map-unknown-species",`Map "${i??n}" filters on unknown species "${l}"`)}),Array.isArray(t.edge_types)&&t.edge_types.forEach((l,x)=>{typeof l=="string"&&!K.includes(l)&&r(`${c}.edge_types[${x}]`,"map-unknown-edge-type",`Map "${i??n}" filters on unknown edge type "${l}"`)})})}let w=new Set,S=new Set,j=new Set;h.forEach((s,u)=>{let n=`edges[${u}]`,t=s.id,c=s.source_id,i=s.target_id,m=s.edge_type;w.has(t)&&e(`${n}.id`,"duplicate-edge-id",`Duplicate edge ID: ${t}`),w.add(t);let l=`e-${c}-${i}`;t!==l&&r(`${n}.id`,"edge-id-convention",`Edge ${t}: id does not match convention "${l}" (stale after a rename?)`);let x=`${c}->${i}:${m}`;S.has(x)&&r(`${n}`,"duplicate-edge-relationship",`Duplicate edge relationship: ${x}`),S.add(x),s.project_id!==p.id&&e(`${n}.project_id`,"project-id-match",`Edge ${t}: project_id does not match project.id`),I.has(c)||e(`${n}.source_id`,"dangling-edge",`Edge ${t}: source_id "${c}" not found in nodes`),I.has(i)||e(`${n}.target_id`,"dangling-edge",`Edge ${t}: target_id "${i}" not found in nodes`),K.includes(m)||e(`${n}.edge_type`,"valid-edge-type",`Edge ${t}: invalid edge_type "${m}"`);let N=R.get(c),D=R.get(i),T=ue[m];N&&D&&T&&(T.some(([V,g])=>V===N.species&&g===D.species)||e(`${n}.edge_type`,"edge-semantics",`Edge ${t}: "${m}" not valid from ${N.species} to ${D.species}`)),m==="composes"&&j.add(`${c}->${i}`)});let F=(s,u,n,t=0)=>{if(t>50)return e(n,"playlist-depth",`Flow ${u}: playlist nesting too deep (possible cycle)`),[];let c=[];for(let i of s)if(i.type==="view")I.has(i.view_id)||e(n,"playlist-ref-exists",`Flow ${u}: playlist references non-existent view "${i.view_id}"`),c.push(i.view_id);else if(i.type==="flow")I.has(i.flow_id)||e(n,"playlist-ref-exists",`Flow ${u}: playlist references non-existent flow "${i.flow_id}"`),i.flow_id===u&&e(n,"playlist-self-cycle",`Flow ${u}: playlist contains itself (direct cycle)`),c.push(i.flow_id);else if(i.type==="condition")i.if_true&&c.push(...F(i.if_true,u,n,t+1)),i.if_false&&c.push(...F(i.if_false,u,n,t+1));else if(i.type==="junction"&&i.cases)for(let m of i.cases)c.push(...F(m.entries||[],u,n,t+1));return c};E.forEach((s,u)=>{let n=s.metadata;if(s.species==="flow"&&n?.playlist?.entries){let t=`nodes[${u}].metadata.playlist`,c=s.id,i=F(n.playlist.entries,c,t);for(let m of i)j.has(`${c}->${m}`)||e(t,"playlist-composes-coherence",`Flow ${c}: playlist references "${m}" but no composes edge exists`)}});let W=new Map,H=new Map;E.forEach((s,u)=>{let n=s.metadata;if(s.species==="flow"&&n?.playlist?.entries){let t=s.id,c=[],i=m=>{for(let l of m)if(l.type==="flow"&&c.push(l.flow_id),l.type==="condition"&&(l.if_true&&i(l.if_true),l.if_false&&i(l.if_false)),l.type==="junction"&&l.cases)for(let x of l.cases)i(x.entries||[])};i(n.playlist.entries),W.set(t,c),H.set(t,`nodes[${u}].metadata.playlist`)}});let Y=new Set,z=new Set,X=s=>{if(z.has(s))return!0;if(Y.has(s))return!1;Y.add(s),z.add(s);for(let u of W.get(s)||[])if(X(u))return e(H.get(s)??"","flow-cycle",`Cycle detected: flow "${s}" -> "${u}"`),!0;return z.delete(s),!1};for(let s of W.keys())X(s);for(let s of te(v))a.push(s);return $()}var ae="journal.jsonl";function L(f,a){return f.filter(e=>e?.species===a).length}function ge(){let f=process.argv[2];f||(console.error("Usage: node validate-bundle.js <path-to-bundle.json>"),process.exit(1)),(0,P.existsSync)(f)||(console.error(`File not found: ${f}`),process.exit(1));let a;try{a=JSON.parse((0,P.readFileSync)(f,"utf8"))}catch(h){console.error(`FATAL: Cannot parse JSON \u2014 ${h.message}`),process.exit(1)}let e=a;(typeof e!="object"||e===null||!e.project||!e.nodes||!e.edges)&&(console.error("FATAL: Missing top-level keys (project, nodes, edges)."),process.exit(1));let r=[],$=!1;if(e.journal===void 0){let h=(0,B.join)((0,B.dirname)(f),ae);if((0,P.existsSync)(h)){let{events:R,findings:I}=ee((0,P.readFileSync)(h,"utf8"));r=I,$=!0,e.journal=R}}let v=Array.isArray(e.nodes)?e.nodes:[],p=Array.isArray(e.edges)?e.edges:[],y=Array.isArray(e.journal)?e.journal:[],_=re(a);console.log(`
+"use strict";var J=require("node:fs"),W=require("node:path");var z=["flow","view","data-model","api-endpoint","acceptance","decision"],F=["idea","discovery","backlog","development","releasing","live","archived"],V=["web","ios","android"],X=["composes","calls","displays","queries","covers","supersedes","generates","impacts"],pe={composes:[["flow","view"],["flow","flow"],["view","flow"],["view","view"]],calls:[["view","api-endpoint"],["flow","api-endpoint"],["api-endpoint","api-endpoint"],["api-endpoint","view"]],displays:[["view","data-model"]],queries:[["api-endpoint","data-model"]],covers:[["acceptance","view"],["acceptance","flow"]],supersedes:[["decision","decision"]],generates:[["decision","acceptance"]],impacts:[["decision","flow"],["decision","view"],["decision","data-model"],["decision","api-endpoint"]]};var le=["saves-time","simplifies","makes-money","reduces-risk","organizes","integrates","connects","reduces-effort","avoids-hassles","reduces-cost","quality","variety","sensory-appeal","informs","reduces-anxiety","rewards-me","nostalgia","design-aesthetics","badge-value","wellness","therapeutic-value","fun-entertainment","attractiveness","provides-access","provides-hope","self-actualization","motivation","heirloom","affiliation-belonging","self-transcendence"];var ue={flow:"F-",view:"V-","data-model":"DM-","api-endpoint":"API-",acceptance:"AC-",decision:"DEC-"};var je=["proposed","approved","enacted","rejected","deprecated","superseded"];function fe(p){switch(p){case"proposed":return"discovery";case"approved":return"backlog";case"enacted":return"live";case"rejected":case"deprecated":case"superseded":return"archived"}}function ge(p){let c=p.metadata?.decision_status;return je.includes(c)?c:"proposed"}var Q={prioritized:"backlog",blocked:"development"};function Z(p){return F.includes(p)?p:Q[p]}var Ce={...Q},Ve={backlog:"idea",...Q};function be(p){let c=s=>typeof s=="string"?s:"";return[...p].sort((s,i)=>{let h=c(s.ts),_=c(i.ts);if(h<_)return-1;if(h>_)return 1;let g=c(s.id),S=c(i.id);return g<S?-1:g>S?1:0})}function me(p){let c=[],s=[];return p.split(/\r?\n/).forEach((h,_)=>{let g=_+1;if(h.trim()==="")return;let S;try{S=JSON.parse(h)}catch(v){s.push({line:g,rule:"journal-line-parse",message:`Line ${g}: not valid JSON \u2014 ${v.message}`,severity:"error"});return}if(typeof S!="object"||S===null||Array.isArray(S)){s.push({line:g,rule:"journal-line-shape",message:`Line ${g}: each journal line must be a single JSON event object.`,severity:"error"});return}let E=S,w=[];if(typeof E.id!="string"&&w.push("id"),typeof E.ts!="string"&&w.push("ts"),typeof E.type!="string"&&w.push("type"),w.length>0){s.push({line:g,rule:"journal-line-shape",message:`Line ${g}: event is missing required envelope field(s): ${w.join(", ")}.`,severity:"error"});return}c.push(E)}),{events:c,findings:s}}var ke={"node.updated":["node_id"],"node.status_changed":["node_id"],"decision.status_changed":["node_id"],"node.deleted":["node_id"],"edge.added":["source_id","target_id"],"ref.added":["node_id"],"ref.removed":["node_id"],"ref.status_changed":["node_id"],"idea.proposed":["node_id"],"request.filed":["node_id"]};function Re(p,c){return p===c?!0:typeof c!="string"?!1:p==="backlog"&&c==="idea"?!0:(Z(p)??p)===(Z(c)??c)}function ye(p){let c=[],s=p.journal;if(s===void 0)return c;if(!Array.isArray(s))return c.push({path:"journal",rule:"journal-shape",message:"journal must be an array of events when present.",severity:"error"}),c;if(s.length===0)return c;let i=r=>typeof r=="string"?r:void 0,h=Array.isArray(p.nodes)?p.nodes:[],_=Array.isArray(p.edges)?p.edges:[],g=new Map,S=new Map;for(let r of h){let l=i(r?.id);if(l!==void 0){g.set(l,r.status);let m=r.metadata,$=m&&typeof m=="object"&&!Array.isArray(m)?m.decision_status:void 0;S.set(l,$??"proposed")}}let E=new Set;for(let r of _){let l=i(r?.id);l!==void 0&&E.add(l)}let w=[];s.forEach((r,l)=>{let m=`journal[${l}]`;if(typeof r!="object"||r===null||Array.isArray(r)){c.push({path:m,rule:"journal-event-shape",message:`journal[${l}]: each event must be a JSON object.`,severity:"error"});return}let $=r,I=[];if(i($.id)===void 0&&I.push("id"),i($.ts)===void 0&&I.push("ts"),i($.type)===void 0&&I.push("type"),I.length>0){c.push({path:m,rule:"journal-event-envelope",message:`journal[${l}]: event is missing required envelope field(s): ${I.join(", ")}.`,severity:"error"});return}w.push({ev:$,index:l})});let v=new Set(g.keys()),k=new Set(E);for(let{ev:r}of w)if(r.type==="node.created"){let l=i(r.node_id);l&&v.add(l)}else if(r.type==="edge.added"){let l=i(r.edge_id);l&&k.add(l)}let x=be(w.map(r=>r.ev)),b=new Set,N=new Map,C=new Map;for(let r of x)if(r.type==="node.created"){let l=i(r.node_id);l&&b.add(l)}else if(r.type==="node.status_changed"){let l=i(r.node_id);if(l&&r.platform===void 0){let m=i(r.to);m!==void 0&&N.set(l,m)}}else if(r.type==="decision.status_changed"){let l=i(r.node_id);if(l){let m=i(r.to);m!==void 0&&C.set(l,m)}}for(let{ev:r,index:l}of w){let m=ke[r.type];if(m)for(let $ of m){let I=i(r[$]);I!==void 0&&!v.has(I)&&c.push({path:`journal[${l}].${$}`,rule:"journal-dangling-node-ref",message:`journal[${l}] (${r.type}): references node "${I}" that never existed in the snapshot or journal.`,severity:"error"})}if(r.type==="deliverable.shipped"&&Array.isArray(r.node_ids)&&r.node_ids.forEach(($,I)=>{let R=i($);R!==void 0&&!v.has(R)&&c.push({path:`journal[${l}].node_ids[${I}]`,rule:"journal-dangling-node-ref",message:`journal[${l}] (${r.type}): references node "${R}" that never existed in the snapshot or journal.`,severity:"error"})}),r.type==="edge.removed"){let $=i(r.edge_id);$!==void 0&&!k.has($)&&c.push({path:`journal[${l}].edge_id`,rule:"journal-dangling-edge-ref",message:`journal[${l}] (edge.removed): references edge "${$}" that never existed in the snapshot or journal.`,severity:"error"})}}for(let[r,l]of g){b.has(r)||c.push({path:"journal",rule:"journal-missing-node-created",message:`Node "${r}" is present in the snapshot but has no node.created event in the journal.`,severity:"error"});let m=N.get(r);m!==void 0&&!Re(m,l)&&c.push({path:"journal",rule:"journal-status-mismatch",message:`Node "${r}": journal's last node.status_changed.to "${m}" disagrees with snapshot status "${String(l)}".`,severity:"error"})}for(let[r,l]of C){if(!S.has(r))continue;let m=S.get(r)??"proposed";l!==m&&c.push({path:"journal",rule:"journal-decision-status-mismatch",message:`Node "${r}": journal's last decision.status_changed.to "${l}" disagrees with snapshot decision_status "${String(m)}".`,severity:"error"})}return c}var _e=["rings","bars"],he=["chips","rows"],ve=["status","species"];var Pe=["journey","system"];function Se(p){return Pe.includes(p)}var we=["flow","view","acceptance"];function $e(p){let c=p?.metadata?.products;if(!Array.isArray(c))return[];let s=new Set,i=[];for(let h of c){if(typeof h!="object"||h===null||Array.isArray(h))continue;let _=h;typeof _.id!="string"||_.id.trim()===""||s.has(_.id)||(s.add(_.id),i.push(_))}return i}var De=["beta","monitoring","deprecated"],Ee=["compact","large"],Ie=2*1024*1024;function Ne(p){let c=p.indexOf(",");if(c===-1)return 0;let s=p.slice(c+1),i=s.endsWith("==")?2:s.endsWith("=")?1:0;return Math.floor(s.length*3/4)-i}function Ae(p){return typeof p=="string"&&!Number.isNaN(Date.parse(p))}function xe(p){let c=[],s=(e,d,n)=>c.push({path:e,rule:d,message:n,severity:"error"}),i=(e,d,n)=>c.push({path:e,rule:d,message:n,severity:"warning"}),h=()=>{let e=c.filter(n=>n.severity==="error"),d=c.filter(n=>n.severity==="warning");return{valid:e.length===0,findings:c,errors:e,warnings:d}};if(typeof p!="object"||p===null||Array.isArray(p))return s("","bundle-shape","Bundle must be an object with project, nodes, and edges."),h();let _=p,g=_.project,S=_.nodes,E=_.edges;if(!g||!S||!E)return s("","bundle-shape","Missing top-level keys (project, nodes, edges)."),h();if(!Array.isArray(S))return s("nodes","bundle-shape","nodes must be an array."),h();if(!Array.isArray(E))return s("edges","bundle-shape","edges must be an array."),h();let w=S,v=E,k=new Map,x=new Set;g.id||s("project.id","project-id-required","project.id is missing"),(typeof g.title!="string"||!g.title.trim())&&s("project.title","title-non-empty","project.title is missing or empty"),g.created_at||s("project.created_at","timestamp-required","project.created_at is missing"),g.updated_at||s("project.updated_at","timestamp-required","project.updated_at is missing"),g.created_at&&!Ae(g.created_at)&&i("project.created_at","iso-timestamp","project.created_at is not a valid ISO 8601 timestamp"),g.updated_at&&!Ae(g.updated_at)&&i("project.updated_at","iso-timestamp","project.updated_at is not a valid ISO 8601 timestamp");let b=g.metadata;b&&b.view_card_variant!==void 0&&!Ee.includes(b.view_card_variant)&&s("project.metadata.view_card_variant","view-card-variant",`project.metadata.view_card_variant must be one of ${Ee.join(", ")} (import rejects other values)`),w.forEach((e,d)=>{let n=`nodes[${d}]`,t=e.id;x.has(t)&&s(`${n}.id`,"duplicate-node-id",`Duplicate node ID: ${t}`),x.add(t),k.set(t,e),(typeof e.title!="string"||!e.title.trim())&&s(`${n}.title`,"title-non-empty",`Node ${t}: title is missing or empty`);let a=e.species,o=ue[a];o&&!(typeof t=="string"&&t.startsWith(o))&&s(`${n}.id`,"species-prefix",`Node ${t}: species "${a}" should have prefix "${o}"`),z.includes(a)||s(`${n}.species`,"valid-species",`Node ${t}: invalid species "${a}"`),e.project_id!==g.id&&s(`${n}.project_id`,"project-id-match",`Node ${t}: project_id "${e.project_id}" does not match project.id "${g.id}"`),F.includes(e.status)||s(`${n}.status`,"valid-status",`Node ${t}: invalid status "${e.status}"`);let f=e.platforms;if(!f||f.length===0)a!=="decision"&&s(`${n}.platforms`,"platforms-non-empty",`Node ${t}: platforms array is empty or missing`);else for(let y of f)V.includes(y)||s(`${n}.platforms`,"valid-platform",`Node ${t}: invalid platform "${y}"`);let u=e.metadata||{};u.stage!==void 0&&!De.includes(u.stage)&&s(`${n}.metadata.stage`,"valid-stage",`Node ${t}: invalid metadata.stage "${u.stage}"`);let A=u.platformNotes;if(A)for(let y of Object.keys(A))V.includes(y)||s(`${n}.metadata.platformNotes`,"valid-platform",`Node ${t}: platformNotes has invalid platform "${y}"`);let P=u.platformStatuses;if(P)for(let[y,j]of Object.entries(P))V.includes(y)?Array.isArray(f)&&!f.includes(y)&&i(`${n}.metadata.platformStatuses`,"platform-statuses-subset",`Node ${t}: platformStatuses covers platform "${y}" not in node.platforms`):s(`${n}.metadata.platformStatuses`,"valid-platform",`Node ${t}: platformStatuses has invalid platform "${y}"`),F.includes(j)||s(`${n}.metadata.platformStatuses`,"valid-status",`Node ${t}: platformStatuses has invalid status "${j}" for platform "${y}"`);let M=u.platformScreenshots;if(M){for(let[y,j]of Object.entries(M))if(typeof j=="string"&&j.startsWith("data:")){let Y=Ne(j);Y>Ie&&i(`${n}.metadata.platformScreenshots`,"screenshot-data-uri-size",`Node ${t}: platformScreenshots.${y} is a ${(Y/(1024*1024)).toFixed(1)}MB data URI, above the ${Ie/(1024*1024)}MB guidance (docs/spec/bundle-format.md \xA7 Asset Values) \u2014 consider a relative path or hosted URL instead`)}}let T=u.gherkin,L=u.values;if(a==="acceptance"?((typeof T!="string"||!T.trim())&&i(`${n}.metadata.gherkin`,"acceptance-gherkin-missing",`Acceptance ${t}: metadata.gherkin is missing or empty (one Given/When/Then scenario expected)`),(!Array.isArray(L)||L.length===0)&&i(`${n}.metadata.values`,"acceptance-values-missing",`Acceptance ${t}: metadata.values is missing or empty (assign 1-3 value elements)`)):(T!==void 0&&i(`${n}.metadata.gherkin`,"gherkin-species",`Node ${t}: metadata.gherkin is only meaningful on acceptance nodes`),L!==void 0&&i(`${n}.metadata.values`,"values-species",`Node ${t}: metadata.values is only meaningful on acceptance nodes`)),Array.isArray(L))for(let y of L)le.includes(y)||s(`${n}.metadata.values`,"valid-value",`Node ${t}: invalid value element "${y}"`);let q=u.refs;if(Array.isArray(q)){let y=new Set;q.forEach((j,Y)=>{let O=j??{},G=`${n}.metadata.refs[${Y}]`,D=O.id;typeof D!="string"||!D.trim()?s(`${G}.id`,"ref-id-required",`Node ${t}: ref is missing an id`):y.has(D)?s(`${G}.id`,"duplicate-ref-id",`Node ${t}: duplicate ref id "${D}"`):y.add(D),(typeof O.url!="string"||!O.url.trim())&&s(`${G}.url`,"ref-url-required",`Node ${t}: ref "${D}" is missing a url`),O.status_mapped!==void 0&&!F.includes(O.status_mapped)&&s(`${G}.status_mapped`,"valid-status",`Node ${t}: ref "${D}" has invalid status_mapped "${O.status_mapped}"`)})}if(u.decision_status!==void 0&&a!=="decision"&&i(`${n}.metadata.decision_status`,"decision-status-wrong-species",`decision_status is meaningful on decision nodes only; "${t}" is a ${a}.`),a==="decision"){let y=ge({metadata:e.metadata}),j=fe(y);e.status!==j&&i(`${n}.status`,"decision-lifecycle-mismatch",`Decision "${t}" is ${y}, whose lifecycle status should be "${j}", but status is "${e.status}" (spec \xA72).`)}if(a==="flow"){let y=u.playlist;!e.metadata||!y||!y.entries?s(`${n}.metadata.playlist`,"flow-playlist-required",`Flow ${t}: missing metadata.playlist.entries`):y.entries.length===0&&i(`${n}.metadata.playlist`,"flow-playlist-empty",`Flow ${t}: playlist is empty`)}});let N=g.root_node_id;N&&!x.has(N)&&s("project.root_node_id","root-node-exists",`project.root_node_id "${N}" does not reference an existing node`);let C=(e,d,n)=>{if(typeof e!="object"||e===null||Array.isArray(e))return;let t=e,a=[["flow_platforms",_e],["view_platforms",he],["minimap_color",ve]];for(let[o,f]of a){let u=t[o];u!==void 0&&(typeof u!="string"||!f.includes(u))&&i(`${d}.${o}`,"map-unknown-display",`${n} sets ${o} to "${String(u)}"; expected one of ${f.join(", ")} (renderers fall back to the default)`)}t.images!==void 0&&typeof t.images!="boolean"&&i(`${d}.images`,"map-unknown-display",`${n} sets images to a non-boolean value (renderers fall back to the default)`)},r=b?.map_display;if(typeof r=="object"&&r!==null&&!Array.isArray(r))for(let[e,d]of Object.entries(r))C(d,`project.metadata.map_display.${e}`,`Map "${e}"`);let l=b?.maps;if(Array.isArray(l)){let e=new Set;l.forEach((d,n)=>{if(typeof d!="object"||d===null||Array.isArray(d))return;let t=d,a=`project.metadata.maps[${n}]`,o=typeof t.id=="string"?t.id:void 0;o!==void 0&&(e.has(o)&&i(`${a}.id`,"map-duplicate-id",`Duplicate map id "${o}"`),e.add(o),Se(o)&&i(`${a}.id`,"map-shadows-built-in",`Map id "${o}" shadows a built-in map and will be ignored`));let f=t.root_node_id;typeof f=="string"&&!x.has(f)&&i(`${a}.root_node_id`,"map-unknown-root",`Map "${o??n}" anchors on "${f}" which does not reference an existing node`),Array.isArray(t.species)&&t.species.forEach((u,A)=>{typeof u=="string"&&!z.includes(u)&&i(`${a}.species[${A}]`,"map-unknown-species",`Map "${o??n}" filters on unknown species "${u}"`)}),Array.isArray(t.edge_types)&&t.edge_types.forEach((u,A)=>{typeof u=="string"&&!X.includes(u)&&i(`${a}.edge_types[${A}]`,"map-unknown-edge-type",`Map "${o??n}" filters on unknown edge type "${u}"`)}),C(t.display,`${a}.display`,`Map "${o??n}"`)})}let m=b?.products,$=new Set;if(Array.isArray(m)){let e=new Set;m.forEach((d,n)=>{if(typeof d!="object"||d===null||Array.isArray(d))return;let t=d,a=`project.metadata.products[${n}]`,o=typeof t.id=="string"?t.id:void 0;o!==void 0&&(e.has(o)?i(`${a}.id`,"product-duplicate-id",`Duplicate product id "${o}" \u2014 the first wins`):(e.add(o),o.trim()!==""&&$.add(o)),/^[a-z0-9]+(-[a-z0-9]+)*$/.test(o)||i(`${a}.id`,"product-invalid-id",`Product id "${o}" is not kebab-case`))})}let I=$.size>0,R=new Map;for(let e of v){if(e.edge_type!=="covers")continue;let d=typeof e.source_id=="string"?e.source_id:void 0,n=typeof e.target_id=="string"?e.target_id:void 0;if(d===void 0||n===void 0)continue;let t=R.get(d)??[];t.push(n),R.set(d,t)}let ee=new Map;if(I)for(let e of $e({metadata:b}))ee.set(e.id,new Set(Array.isArray(e.platforms)?e.platforms:[]));let te=new Map,ne=new Map;if(w.forEach((e,d)=>{let n=typeof e.id=="string"?e.id:`#${d}`,t=e.species,a=`nodes[${d}]`;ne.set(n,d);let o=e.metadata??{},f=typeof o.product=="string"?o.product:void 0,u=t!==void 0&&we.includes(t);if(f!==void 0&&!u){let M=z.includes(t)?`${t} membership is derived from consumers and must not be stored`:"metadata.product is only meaningful on flow, view, and acceptance nodes";i(`${a}.metadata.product`,"product-membership-wrong-species",`Node ${n}: ${M}`);return}if(!u)return;if(f===void 0){if(!I)return;t==="acceptance"?R.has(n)||i(`${a}.metadata.product`,"acceptance-product-unassigned",`Acceptance ${n} covers nothing and names no product \u2014 it will show only under "All products"`):i(`${a}.metadata.product`,"unassigned-membership",`Node ${n}: no product membership \u2014 it will show only under "All products"`);return}if(te.set(n,f),!$.has(f)){i(`${a}.metadata.product`,"product-unknown-reference",`Node ${n}: product "${f}" is not declared on the project`);return}let A=ee.get(f),P=Array.isArray(e.platforms)?e.platforms:[];if(A)for(let M of P)typeof M=="string"&&!A.has(M)&&i(`${a}.platforms`,"product-platform-not-in-menu",`Node ${n}: platform "${M}" is not in product "${f}"'s menu`)}),I)for(let[e,d]of R){let n=ne.get(e);if(n===void 0)continue;let t=new Set(d.map(a=>te.get(a)).filter(a=>!!a));t.size>1&&i(`nodes[${n}].metadata.product`,"acceptance-covers-span-products",`Acceptance ${e} covers anchors in ${[...t].sort().join(" and ")} \u2014 statuses may conflate products`)}let se=new Set,oe=new Set,ie=new Set;v.forEach((e,d)=>{let n=`edges[${d}]`,t=e.id,a=e.source_id,o=e.target_id,f=e.edge_type;se.has(t)&&s(`${n}.id`,"duplicate-edge-id",`Duplicate edge ID: ${t}`),se.add(t);let u=`e-${a}-${o}`;t!==u&&i(`${n}.id`,"edge-id-convention",`Edge ${t}: id does not match convention "${u}" (stale after a rename?)`);let A=`${a}->${o}:${f}`;oe.has(A)&&i(`${n}`,"duplicate-edge-relationship",`Duplicate edge relationship: ${A}`),oe.add(A),e.project_id!==g.id&&s(`${n}.project_id`,"project-id-match",`Edge ${t}: project_id does not match project.id`),x.has(a)||s(`${n}.source_id`,"dangling-edge",`Edge ${t}: source_id "${a}" not found in nodes`),x.has(o)||s(`${n}.target_id`,"dangling-edge",`Edge ${t}: target_id "${o}" not found in nodes`),X.includes(f)||s(`${n}.edge_type`,"valid-edge-type",`Edge ${t}: invalid edge_type "${f}"`);let P=k.get(a),M=k.get(o),T=pe[f];P&&M&&T&&(T.some(([q,ce])=>q===P.species&&ce===M.species)||s(`${n}.edge_type`,"edge-semantics",`Edge ${t}: "${f}" not valid from ${P.species} to ${M.species}`)),f==="composes"&&ie.add(`${a}->${o}`)});let B=(e,d,n,t=0)=>{if(t>50)return s(n,"playlist-depth",`Flow ${d}: playlist nesting too deep (possible cycle)`),[];let a=[];for(let o of e)if(o.type==="view")x.has(o.view_id)||s(n,"playlist-ref-exists",`Flow ${d}: playlist references non-existent view "${o.view_id}"`),a.push(o.view_id);else if(o.type==="flow")x.has(o.flow_id)||s(n,"playlist-ref-exists",`Flow ${d}: playlist references non-existent flow "${o.flow_id}"`),o.flow_id===d&&s(n,"playlist-self-cycle",`Flow ${d}: playlist contains itself (direct cycle)`),a.push(o.flow_id);else if(o.type==="condition")o.if_true&&a.push(...B(o.if_true,d,n,t+1)),o.if_false&&a.push(...B(o.if_false,d,n,t+1));else if(o.type==="junction"&&o.cases)for(let f of o.cases)a.push(...B(f.entries||[],d,n,t+1));return a};w.forEach((e,d)=>{let n=e.metadata;if(e.species==="flow"&&n?.playlist?.entries){let t=`nodes[${d}].metadata.playlist`,a=e.id,o=B(n.playlist.entries,a,t);for(let f of o)ie.has(`${a}->${f}`)||s(t,"playlist-composes-coherence",`Flow ${a}: playlist references "${f}" but no composes edge exists`)}});let K=new Map,re=new Map;w.forEach((e,d)=>{let n=e.metadata;if(e.species==="flow"&&n?.playlist?.entries){let t=e.id,a=[],o=f=>{for(let u of f)if(u.type==="flow"&&a.push(u.flow_id),u.type==="condition"&&(u.if_true&&o(u.if_true),u.if_false&&o(u.if_false)),u.type==="junction"&&u.cases)for(let A of u.cases)o(A.entries||[])};o(n.playlist.entries),K.set(t,a),re.set(t,`nodes[${d}].metadata.playlist`)}});let ae=new Set,H=new Set,de=e=>{if(H.has(e))return!0;if(ae.has(e))return!1;ae.add(e),H.add(e);for(let d of K.get(e)||[])if(de(d))return s(re.get(e)??"","flow-cycle",`Cycle detected: flow "${e}" -> "${d}"`),!0;return H.delete(e),!1};for(let e of K.keys())de(e);for(let e of ye(_))c.push(e);return h()}var Me="journal.jsonl";function U(p,c){return p.filter(s=>s?.species===c).length}function Te(){let p=process.argv[2];p||(console.error("Usage: node validate-bundle.js <path-to-bundle.json>"),process.exit(1)),(0,J.existsSync)(p)||(console.error(`File not found: ${p}`),process.exit(1));let c;try{c=JSON.parse((0,J.readFileSync)(p,"utf8"))}catch(v){console.error(`FATAL: Cannot parse JSON \u2014 ${v.message}`),process.exit(1)}let s=c;(typeof s!="object"||s===null||!s.project||!s.nodes||!s.edges)&&(console.error("FATAL: Missing top-level keys (project, nodes, edges)."),process.exit(1));let i=[],h=!1;if(s.journal===void 0){let v=(0,W.join)((0,W.dirname)(p),Me);if((0,J.existsSync)(v)){let{events:k,findings:x}=me((0,J.readFileSync)(v,"utf8"));i=x,h=!0,s.journal=k}}let _=Array.isArray(s.nodes)?s.nodes:[],g=Array.isArray(s.edges)?s.edges:[],S=Array.isArray(s.journal)?s.journal:[],E=xe(c);console.log(`
   Arkaik Bundle Validation`),console.log(`  =======================
-`),console.log(`  Nodes: ${v.length} (${L(v,"view")} views, ${L(v,"flow")} flows, ${L(v,"data-model")} data-models, ${L(v,"api-endpoint")} api-endpoints, ${L(v,"acceptance")} acceptances)`),console.log(`  Edges: ${p.length}`),$?console.log(`  Journal: ${y.length} event(s) from ${ae} sidecar`):y.length>0&&console.log(`  Journal: ${y.length} embedded event(s)`),console.log(""),_.warnings.length>0&&(console.log(`  Warnings: ${_.warnings.length}`),_.warnings.forEach(h=>console.log(`    WARN: ${h.message}`)),console.log(""));let E=[...r.map(h=>h.message),..._.errors.map(h=>h.message)];E.length===0&&(console.log(`  Result: VALID
-`),process.exit(0)),console.log(`  Errors: ${E.length}`),E.forEach(h=>console.log(`    ERROR: ${h}`)),console.log(`
+`),console.log(`  Nodes: ${_.length} (${U(_,"view")} views, ${U(_,"flow")} flows, ${U(_,"data-model")} data-models, ${U(_,"api-endpoint")} api-endpoints, ${U(_,"acceptance")} acceptances)`),console.log(`  Edges: ${g.length}`),h?console.log(`  Journal: ${S.length} event(s) from ${Me} sidecar`):S.length>0&&console.log(`  Journal: ${S.length} embedded event(s)`),console.log(""),E.warnings.length>0&&(console.log(`  Warnings: ${E.warnings.length}`),E.warnings.forEach(v=>console.log(`    WARN: ${v.message}`)),console.log(""));let w=[...i.map(v=>v.message),...E.errors.map(v=>v.message)];w.length===0&&(console.log(`  Result: VALID
+`),process.exit(0)),console.log(`  Errors: ${w.length}`),w.forEach(v=>console.log(`    ERROR: ${v}`)),console.log(`
   Result: INVALID
-`),process.exit(1)}ge();
+`),process.exit(1)}Te();

package/dist/assets/skill/skill.md

@@ -1,6 +1,6 @@
 ---
 name: arkaik
-version: 3.0.0
+version: 3.2.0
 description: >
   Maintain the Arkaik product graph map for {{PRODUCT_NAME}} — add, update, or
   remove nodes and edges in the ProjectBundle JSON that describes its screens,
@@ -44,6 +44,26 @@ one the first time you make a change (see [Dual-write](#dual-write-snapshot--jou
 > | `{{BUNDLE_PATH}}` | Path to the snapshot | `docs/arkaik/bundle.json` |
 > | `{{JOURNAL_PATH}}` | Path to the journal sidecar | `docs/arkaik/journal.jsonl` |
 
+> **Check this first: is the map a file, or an account project?**
+>
+> If `docs/arkaik/arkaik.json` exists in this repository, the map is **hosted** —
+> it lives in an arkaik account, not in a file here. Everything below about
+> *what* to record still applies; everything about *how* to write it does not.
+>
+> | | File map | Hosted map (`docs/arkaik/arkaik.json` present) |
+> |---|---|---|
+> | Where it lives | `{{BUNDLE_PATH}}` in this repo | the account, reached over HTTP |
+> | How you edit it | patch the JSON, append to the journal | the `arkaik-mcp` tools (`create_node`, `update_node`, …) |
+> | Dual-write | you do it, by hand | the server does it — every mutation derives its own journal events |
+>
+> **Do not create or edit `{{BUNDLE_PATH}}` for a hosted map.** Nothing reads it,
+> the account never sees the change, and the next person to look finds two maps
+> disagreeing. If the MCP tools are unavailable, say so and stop rather than
+> falling back to the file — a silent fallback is the failure nobody notices.
+>
+> The tool catalog is identical in both modes, so the rest of this skill reads
+> the same either way. Setup: [hosted-projects.md](https://github.com/alexisbohns/arkaik/blob/main/docs/hosted-projects.md).
+
 ## When to Update the Map
 
 Update the map as a side-effect of your main work whenever you:
@@ -154,6 +174,9 @@ larger restructuring. Follow these rules strictly:
   capitalized words; physical tables/views use the exact DB identifier verbatim.
 - Every `node.project_id` must match `project.id`
 - `platforms` must contain at least one of: `"web"`, `"ios"`, `"android"`
+- If the project declares products (`project.metadata.products`), flows and views
+  also carry `metadata.product` and their `platforms` stay inside that product's
+  menu — see [Products](#products--which-app-does-this-node-belong-to)
 - Flow nodes must have `metadata.playlist` with at least one entry
 
 **Edge rules:**
@@ -161,7 +184,7 @@ larger restructuring. Follow these rules strictly:
 - Every `source_id` and `target_id` must reference existing node IDs
 - Edge type semantics:
   - `composes`: flow -> view, flow -> flow (sub-flow), view -> flow (triggers)
-  - `calls`: view -> api-endpoint, flow -> api-endpoint, api-endpoint -> api-endpoint (endpoint fan-out to internal/external APIs)
+  - `calls`: view -> api-endpoint, flow -> api-endpoint, api-endpoint -> api-endpoint (endpoint fan-out to internal/external APIs), api-endpoint -> view (the server initiates: webhook, SSE, push)
   - `displays`: view -> data-model
   - `queries`: api-endpoint -> data-model
   - `covers`: acceptance -> view, acceptance -> flow
@@ -251,8 +274,10 @@ Creating a new acceptance + covers edge is itself a dual-write: append
 - `Given` encodes render variants ("Given the pebble has a picture attached…").
 - `platforms` lists only the platforms where the behavior is *expected* — a
   mobile-only behavior is `["ios", "android"]`, not backlog-on-web.
-- `covers` edges: acceptance → view or acceptance → flow. Zero edges = a
-  product-level acceptance (legal). Several = the behavior spans surfaces.
+- `covers` edges: acceptance → view or acceptance → flow. Zero edges = an
+  anchorless acceptance in **intake** (legal): an idea filed before its flows and
+  views exist, carrying `metadata.product` until it has anchors to derive
+  membership from. Several = the behavior spans surfaces.
 - Statuses reuse the standard lifecycle; "shipped" = `live`.
 
 **Example** — iOS ships the draw-in animation:
@@ -284,6 +309,72 @@ worse than a missing one. Consult `references/values.md` (one-line definitions
 per element) only when actually mapping — do not load it otherwise.
 <!-- values:end -->
 
+## Products — which app does this node belong to?
+
+A project may describe a **family** of apps sharing one graph: an end-user app, a
+web-only back office, a public API. Each is a **product**, declared once in
+`project.metadata.products` with an `id`, a `title`, and the `platforms` it may
+ship on. Most projects declare none, and a project with no `products` key behaves
+exactly as it always has — do not invent products for one.
+
+But when a project *does* declare them, **you are the only author of membership**:
+no form, panel, or dialog in the app writes any of the fields below. If you don't
+write them, nobody does.
+
+**Where membership is stored — and where it must never be:**
+
+| Species | What you write |
+|---|---|
+| `flow`, `view` | `metadata.product` — exactly one declared product id |
+| `acceptance` | Usually **nothing**. Membership comes from the views and flows its `covers` edges reach. Write `metadata.product` only when the acceptance covers nothing (below) |
+| `data-model`, `api-endpoint` | **Never.** Membership is derived from whoever consumes them, walking `calls` / `displays` / `queries` inward from the flows and views. Writing `metadata.product` here is a validator warning (`product-membership-wrong-species`) |
+
+That last row is the one to get right. The system layer is shared substrate: a
+data model both the end-user app and the admin touch belongs to both, and a
+stored key could only ever claim one of them.
+
+**Keep `platforms` inside the product's menu.** `node.platforms` stays
+authoritative and unchanged in meaning, but it *should* be a subset of its
+product's `platforms`. A view in a web-only admin product is `["web"]`, not
+`["web", "ios", "android"]`. Readers intersect the two lists, so an out-of-menu
+platform is dropped from every display anyway and only earns you a
+`product-platform-not-in-menu` warning.
+
+**An anchorless acceptance should name its product.** An acceptance with zero
+`covers` edges is legal — a product-level promise — but it has no anchor to
+derive membership from, so it sits under "All products" only until you say which
+app it is about (`acceptance-product-unassigned`):
+
+```json
+{
+  "id": "AC-audit-log-retention",
+  "project_id": "{{PROJECT_ID}}",
+  "species": "acceptance",
+  "title": "Audit log retention",
+  "status": "backlog",
+  "platforms": ["web"],
+  "metadata": {
+    "gherkin": "Given an admin action older than 90 days, When I open the audit log, Then it is no longer listed.",
+    "values": ["reduces-risk"],
+    "product": "admin"
+  }
+}
+```
+
+This is the one rule no example project can teach you by imitation: in the
+Pebbles seed all three acceptances anchor on a view or flow via `covers`, so
+every one of them derives its product and stores nothing. The anchorless case has
+no worked example anywhere — write the key yourself.
+
+**Stored maps take a product too.** A `MapDefinition` in `project.metadata.maps`
+has an optional `product`, which makes "the admin systems map" data rather than a
+feature request. As with everything above, there is no UI control for it: a map's
+`product` is set by writing it.
+
+When in doubt, leave membership off. An unassigned flow or view is a visible
+triage state the validator names (`unassigned-membership`); a *wrongly* assigned
+one is invisible, and quietly wrong in every rollup that reads it.
+
 ## Full Schema Reference
 
 For the complete TypeScript types, allowed values for `status`, `species`,
@@ -321,6 +412,12 @@ known type whenever one fits.
 
 ## Bootstrap: Generating a Map from Scratch
 
+**Check for the bootstrap skill first.** If the `arkaik-bootstrap` skill is
+installed beside this one — or can be installed with `arkaik init --bootstrap` —
+the bootstrap method supersedes this section for from-scratch and
+retro-population runs. The steps below remain the fallback when the bootstrap
+tooling is unavailable.
+
 If the project doesn't have a map yet and the user asks you to create one:
 
 1. Scan the codebase for routes/pages, models, and API endpoints
@@ -340,5 +437,6 @@ If the project doesn't have a map yet and the user asks you to create one:
 6. Save the snapshot to `{{BUNDLE_PATH}}` and the journal to `{{JOURNAL_PATH}}`
    (or ask the user where they want them)
 
-Full generation is the **only** sanctioned non-surgical case. For every
-subsequent change, use a surgical patch paired with an appended event.
+Full generation — via this section or the bootstrap method — is the **only**
+sanctioned non-surgical case. For every subsequent change, use a surgical patch
+paired with an appended event.