@bevel-software/platform-shared 0.4.1 → 0.5.1

package/dist/workspace/join-request.js

@@ -0,0 +1,102 @@
+/**
+ * The join-request naming convention — how "asking to join a group" rides on
+ * plain change requests with zero new backend state.
+ *
+ * A join request IS a change request: a draft branch carrying one commit that
+ * adds the requester to the group's `access.md` body `read:` list, opened
+ * against the default branch. What makes it recognisable — to the `Requested`
+ * chip, to the manager-side proposals surface, to idempotency — is only this
+ * branch-name convention. Both sides (backend, frontend) read it from here so
+ * they can never drift.
+ *
+ *   <email-localpart>/join-<group-kebab>-<groupTag>-<requesterTag>
+ *
+ * follows the workspace's existing `<email-localpart>/<kebab-slug>` draft
+ * convention, so join branches sort with the requester's other drafts and
+ * the branch-authorship delete rule applies unchanged.
+ *
+ * WHY TWO TAGS: the localpart and the kebab slug are both LOSSY, and each
+ * loss has its own failure:
+ *
+ *  - `groupTag` — over the EXACT group name, recomputable by anyone who
+ *    knows the group. `Finance!` and `finance` share the slug `finance`;
+ *    without this tag, listing one group's requests would match the other's
+ *    branches, read the wrong `access.md` (unchanged on that branch), see an
+ *    empty diff and SETTLE the request — closing a change request and
+ *    deleting a branch that belong to a different group. The settle decision
+ *    is "the diff is empty", so group identity must be exact BEFORE the diff
+ *    is consulted, and `isJoinBranchFor` recomputes this tag to make it so.
+ *  - `requesterTag` — over the full email (+ group), NOT recomputable by a
+ *    reader (a manager listing requests does not know each requester's
+ *    email; `isJoinBranchFor` matches its shape only). It exists so
+ *    `ali@bevel.software` and `ali@other.com` never share a branch — else
+ *    the second requester's commit lands on the first one's branch.
+ *
+ * The tags are collision-avoidance devices, not a security boundary —
+ * nothing grants access based on a branch name. Grants happen through the
+ * ordinary access mutation path, and settling only ever closes a request
+ * whose file adds nothing over the default branch.
+ */
+/** Group name → the kebab slug used in the join branch (lossy by design). */
+export function kebabGroupName(group) {
+    return group
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, '-')
+        .replace(/[^a-z0-9-]/g, '')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+/** Length of each branch-name tag, in base-36 characters. */
+const TAG_LENGTH = 7;
+/**
+ * Short deterministic tag over an exact string (FNV-1a, base36).
+ *
+ * Synchronous and dependency-free so the same value is derivable in the
+ * browser and on the server; `crypto.subtle` is async and would force this
+ * whole convention to become promise-shaped for no benefit. Not a hash in the
+ * security sense and does not need to be — see the module note.
+ */
+function shortTag(input) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+        hash ^= input.charCodeAt(i);
+        // FNV prime, via shifts so the whole thing stays in 32-bit int math.
+        hash = (hash + ((hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24))) >>> 0;
+    }
+    return hash.toString(36).padStart(TAG_LENGTH, '0').slice(-TAG_LENGTH);
+}
+/** The exact-group tag — recomputable from the group name alone. */
+function groupTag(group) {
+    return shortTag(`g:${group}`);
+}
+/** The deterministic join branch for (requester, group). */
+export function joinBranchFor(email, group) {
+    const normalizedEmail = email.trim().toLowerCase();
+    const localpart = normalizedEmail.split('@')[0] || normalizedEmail;
+    const slug = kebabGroupName(group);
+    const requester = shortTag(`u:${normalizedEmail}\n${group}`);
+    // A group whose name has no alphanumerics at all (`!!!`) kebabs to '' — the
+    // tags alone still yield a valid, matchable branch.
+    const middle = slug ? `${slug}-` : '';
+    return `${localpart}/join-${middle}${groupTag(group)}-${requester}`;
+}
+/**
+ * Does `branch` look like SOMEBODY's join branch for EXACTLY `group`?
+ *
+ * The group half (slug + `groupTag`) is recomputed and must match — this is
+ * what keeps slug-colliding groups (`Finance!` vs `finance`) from seeing,
+ * and worse settling, each other's requests. The requester half cannot be
+ * recomputed (the reader has no email) and matches by shape; the requester's
+ * identity comes from the change request's own attribution.
+ */
+export function isJoinBranchFor(branch, group) {
+    const slug = kebabGroupName(group);
+    const middle = slug ? `${escapeRegExp(slug)}-` : '';
+    const requester = `[0-9a-z]{${TAG_LENGTH}}`;
+    return new RegExp(`^[^/]+/join-${middle}${groupTag(group)}-${requester}$`).test(branch);
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=join-request.js.map

package/dist/workspace/join-request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"join-request.js","sourceRoot":"","sources":["../../src/workspace/join-request.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,6EAA6E;AAC7E,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAO,KAAK;SACT,IAAI,EAAE;SACN,WAAW,EAAE;SACb,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC;SAC1B,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAC3B,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,GAAG,CAAC,CAAC;AAErB;;;;;;;GAOG;AACH,SAAS,QAAQ,CAAC,KAAa;IAC7B,IAAI,IAAI,GAAG,UAAU,CAAC;IACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC5B,qEAAqE;QACrE,IAAI,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAC/F,CAAC;IACD,OAAO,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,CAAC;AACxE,CAAC;AAED,oEAAoE;AACpE,SAAS,QAAQ,CAAC,KAAa;IAC7B,OAAO,QAAQ,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC;AAChC,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,aAAa,CAAC,KAAa,EAAE,KAAa;IACxD,MAAM,eAAe,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACnD,MAAM,SAAS,GAAG,eAAe,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,eAAe,CAAC;IACnE,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACnC,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,eAAe,KAAK,KAAK,EAAE,CAAC,CAAC;IAC7D,4EAA4E;IAC5E,oDAAoD;IACpD,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACtC,OAAO,GAAG,SAAS,SAAS,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,SAAS,EAAE,CAAC;AACtE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,KAAa;IAC3D,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACpD,MAAM,SAAS,GAAG,YAAY,UAAU,GAAG,CAAC;IAC5C,OAAO,IAAI,MAAM,CAAC,eAAe,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,SAAS,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC1F,CAAC;AAED,SAAS,YAAY,CAAC,CAAS;IAC7B,OAAO,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AAClD,CAAC"}

package/dist/workspace/kb-layout.d.ts

@@ -6,19 +6,25 @@
  *
  *   <kbDirName>/
  *   ├── KnowledgeBase/   ← all team ontologies live here (the knowledge graph)
+ *   ├── Groups/          ← one folder per group; each holds BOTH skills and tools
  *   ├── Data/            ← agent-produced records; parsed like KnowledgeBase/
  *   ├── Agents/          ← .agent files — agent role configurations (not the graph)
  *   ├── Pipelines/       ← .pipeline files — execution-layer processes (not the graph)
- *   ├── Skills/          ← reusable agent skills (NOT part of the graph)
- *   ├── Tools/           ← user-authored tool manuals (*.tool; not the graph)
  *   ├── roles.yaml       ← identity → role mapping
  *   └── access.md        ← repo-root access-control rules
  *
+ * RESERVED IS NOT THE SAME AS CREATED. Core seeds the first two only
+ * (`CORE_REQUIRED_DIRS`); `Data/`, `Agents/` and `Pipelines/` scaffold an
+ * agentic execution layer that a distribution layers on. Their names stay here
+ * regardless, because reserving a name is what stops a KB that HAS the folder
+ * from having it treated as ordinary content — the file tree would otherwise
+ * fold it into Knowledge as a stray directory.
+ *
  * These names are the single source of truth for both sides of the app:
  *  - Backend: the graph parser discovers ontologies under the
- *    {@link ONTOLOGY_ROOTS} (`KnowledgeBase/` and `Data/`); `Skills/`,
- *    `Tools/`, `Agents/`, `Pipelines/` (and anything else at the root) are
- *    ignored by parsing, validation, and the diagram.
+ *    {@link ONTOLOGY_ROOTS} (`KnowledgeBase/` and `Data/`); `Groups/`,
+ *    `Agents/`, `Pipelines/` (and anything else at the root) are ignored by
+ *    parsing, validation, and the diagram.
  *  - Frontend: the file tree renders these root folders as distinct
  *    top-level sections.
  *
@@ -26,15 +32,61 @@
  */
 /** Folder under the repo root that contains all team ontologies. */
 export declare const KNOWLEDGE_BASE_DIR = "KnowledgeBase";
-/** Folder under the repo root that holds reusable agent skills (not graph nodes). */
-export declare const SKILLS_DIR = "Skills";
 /**
- * Folder under the repo root that holds user-authored tool manuals (`*.tool`
- * files). Each `.tool` is a UTCP manual (inline / http / mcp) that the MCP/UTCP
- * endpoint loads for any user who can read it (access-controlled like Skills).
- * Not part of the knowledge graph.
+ * Folder under the repo root that holds the groups.
+ *
+ *   Groups/<Group>/<skill>/SKILL.md   a skill
+ *   Groups/<Group>/<name>.tool        a tool manual
+ *   Groups/<Group>/access.md          who can read/write the whole group
+ *
+ * One folder is one group. Skills and tools live TOGETHER inside it because
+ * they share a single access boundary: a tool a group cannot read is a skill
+ * that group cannot run, so splitting them across two roots meant maintaining
+ * the same permission twice and letting them drift.
+ *
+ * A group is not a registry of unique names — it is a folder. The same
+ * integration may exist in several groups as separate files (`Everyone/
+ * notion.tool` and `Finance/notion.tool`), each with its own credentials and
+ * its own access rule. That duplication is the design, not an accident.
+ */
+export declare const GROUPS_DIR = "Groups";
+/**
+ * The reserved name prefix marking a personal folder under `Groups/` —
+ * `Groups/personal-<user-id>/` is where a person's own skills live: created
+ * implicitly on their first personal skill, private by default (its seeded
+ * `access.md` names only its owner), and never listed as a group.
+ *
+ * The marker is STRUCTURAL on purpose: every surface that enumerates groups
+ * (catalog scan, sidebar, counts) filters on the name alone, with no access
+ * lookup needed, and the group-creation endpoint refuses names carrying the
+ * prefix — so a regular group can never squat on someone's personal folder.
+ */
+export declare const PERSONAL_GROUP_PREFIX = "personal-";
+/**
+ * The one personal folder name for a user — keyed to the STABLE user id, not
+ * the email: emails change, and a folder keyed to one would be orphaned the
+ * day it does. Ids are opaque, so the name carries no PII into git history
+ * (which this platform never rewrites). `branchSegment` is THE segment
+ * sanitizer — the id lands in the folder name exactly as it lands in the
+ * user's suggestion-branch names, so the two spellings can never disagree.
+ */
+export declare function personalGroupFolderName(userId: string): string;
+/** Whether a `Groups/` child is somebody's personal folder. */
+export declare function isPersonalGroupFolder(folderName: string): boolean;
+/**
+ * The group a repo-root-relative path belongs to, or `null` for content that
+ * sits outside any group.
+ *
+ *   Groups/GTM/heyreach-campaign/SKILL.md → 'GTM'
+ *   Groups/GTM/heyreach.tool              → 'GTM'
+ *   Groups/loose-skill/SKILL.md           → null    (no group folder)
+ *   KnowledgeBase/Product/…               → null    (not a group root)
+ *
+ * Returns null rather than throwing because a group is a property SOME paths
+ * have. Callers bucket by it; nothing requires it. An ungrouped skill is a
+ * real, supported state — the prototype calls those "yours alone".
  */
-export declare const TOOLS_DIR = "Tools";
+export declare function groupOfPath(repoRelativePath: string): string | null;
 /**
  * Folder under the repo root for agent-produced records (pipeline instances,
  * work items, intermediate outputs). Parsed exactly like `KnowledgeBase/`:
@@ -58,7 +110,7 @@ export declare const NODETYPE_DIR = "NodeTypes";
 export declare const ONTOLOGY_MARKERS: Set<string>;
 /**
  * A named ontology id, or `null` for the neutral bucket — content that belongs
- * to no named ontology (root config, `Skills/`, root-level `Knowledge/`, etc.).
+ * to no named ontology (root config, `Groups/`, root-level `Knowledge/`, etc.).
  * The named id is the repo-root-relative path of the ontology directory,
  * e.g. `KnowledgeBase/Product` or `KnowledgeBase/IT Architecture`.
  */

package/dist/workspace/kb-layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kb-layout.d.ts","sourceRoot":"","sources":["../../src/workspace/kb-layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,oEAAoE;AACpE,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAElD,qFAAqF;AACrF,eAAO,MAAM,UAAU,WAAW,CAAC;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,SAAS,UAAU,CAAC;AAEjC;;;;GAIG;AACH,eAAO,MAAM,QAAQ,SAAS,CAAC;AAE/B,0GAA0G;AAC1G,eAAO,MAAM,UAAU,WAAW,CAAC;AAEnC,6GAA6G;AAC7G,eAAO,MAAM,aAAa,cAAc,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAAmC,CAAC;AAEhF,gFAAgF;AAChF,eAAO,MAAM,aAAa,cAAc,CAAC;AAEzC,qFAAqF;AACrF,eAAO,MAAM,YAAY,cAAc,CAAC;AAExC,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,aAAyC,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,IAAI,CAAC"}
+{"version":3,"file":"kb-layout.d.ts","sourceRoot":"","sources":["../../src/workspace/kb-layout.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,oEAAoE;AACpE,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAElD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,UAAU,WAAW,CAAC;AAEnC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,cAAc,CAAC;AAEjD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,+DAA+D;AAC/D,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOnE;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,SAAS,CAAC;AAE/B,0GAA0G;AAC1G,eAAO,MAAM,UAAU,WAAW,CAAC;AAEnC,6GAA6G;AAC7G,eAAO,MAAM,aAAa,cAAc,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAAmC,CAAC;AAEhF,gFAAgF;AAChF,eAAO,MAAM,aAAa,cAAc,CAAC;AAEzC,qFAAqF;AACrF,eAAO,MAAM,YAAY,cAAc,CAAC;AAExC,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,aAAyC,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,IAAI,CAAC"}

package/dist/workspace/kb-layout.js

@@ -1,3 +1,4 @@
+import { branchSegment } from '../git/branchAuthor.js';
 /**
  * Top-level layout of the KB repo (inside the `KB_DIR_NAME` clone).
  *
@@ -6,19 +7,25 @@
  *
  *   <kbDirName>/
  *   ├── KnowledgeBase/   ← all team ontologies live here (the knowledge graph)
+ *   ├── Groups/          ← one folder per group; each holds BOTH skills and tools
  *   ├── Data/            ← agent-produced records; parsed like KnowledgeBase/
  *   ├── Agents/          ← .agent files — agent role configurations (not the graph)
  *   ├── Pipelines/       ← .pipeline files — execution-layer processes (not the graph)
- *   ├── Skills/          ← reusable agent skills (NOT part of the graph)
- *   ├── Tools/           ← user-authored tool manuals (*.tool; not the graph)
  *   ├── roles.yaml       ← identity → role mapping
  *   └── access.md        ← repo-root access-control rules
  *
+ * RESERVED IS NOT THE SAME AS CREATED. Core seeds the first two only
+ * (`CORE_REQUIRED_DIRS`); `Data/`, `Agents/` and `Pipelines/` scaffold an
+ * agentic execution layer that a distribution layers on. Their names stay here
+ * regardless, because reserving a name is what stops a KB that HAS the folder
+ * from having it treated as ordinary content — the file tree would otherwise
+ * fold it into Knowledge as a stray directory.
+ *
  * These names are the single source of truth for both sides of the app:
  *  - Backend: the graph parser discovers ontologies under the
- *    {@link ONTOLOGY_ROOTS} (`KnowledgeBase/` and `Data/`); `Skills/`,
- *    `Tools/`, `Agents/`, `Pipelines/` (and anything else at the root) are
- *    ignored by parsing, validation, and the diagram.
+ *    {@link ONTOLOGY_ROOTS} (`KnowledgeBase/` and `Data/`); `Groups/`,
+ *    `Agents/`, `Pipelines/` (and anything else at the root) are ignored by
+ *    parsing, validation, and the diagram.
  *  - Frontend: the file tree renders these root folders as distinct
  *    top-level sections.
  *
@@ -26,15 +33,73 @@
  */
 /** Folder under the repo root that contains all team ontologies. */
 export const KNOWLEDGE_BASE_DIR = 'KnowledgeBase';
-/** Folder under the repo root that holds reusable agent skills (not graph nodes). */
-export const SKILLS_DIR = 'Skills';
 /**
- * Folder under the repo root that holds user-authored tool manuals (`*.tool`
- * files). Each `.tool` is a UTCP manual (inline / http / mcp) that the MCP/UTCP
- * endpoint loads for any user who can read it (access-controlled like Skills).
- * Not part of the knowledge graph.
+ * Folder under the repo root that holds the groups.
+ *
+ *   Groups/<Group>/<skill>/SKILL.md   a skill
+ *   Groups/<Group>/<name>.tool        a tool manual
+ *   Groups/<Group>/access.md          who can read/write the whole group
+ *
+ * One folder is one group. Skills and tools live TOGETHER inside it because
+ * they share a single access boundary: a tool a group cannot read is a skill
+ * that group cannot run, so splitting them across two roots meant maintaining
+ * the same permission twice and letting them drift.
+ *
+ * A group is not a registry of unique names — it is a folder. The same
+ * integration may exist in several groups as separate files (`Everyone/
+ * notion.tool` and `Finance/notion.tool`), each with its own credentials and
+ * its own access rule. That duplication is the design, not an accident.
+ */
+export const GROUPS_DIR = 'Groups';
+/**
+ * The reserved name prefix marking a personal folder under `Groups/` —
+ * `Groups/personal-<user-id>/` is where a person's own skills live: created
+ * implicitly on their first personal skill, private by default (its seeded
+ * `access.md` names only its owner), and never listed as a group.
+ *
+ * The marker is STRUCTURAL on purpose: every surface that enumerates groups
+ * (catalog scan, sidebar, counts) filters on the name alone, with no access
+ * lookup needed, and the group-creation endpoint refuses names carrying the
+ * prefix — so a regular group can never squat on someone's personal folder.
+ */
+export const PERSONAL_GROUP_PREFIX = 'personal-';
+/**
+ * The one personal folder name for a user — keyed to the STABLE user id, not
+ * the email: emails change, and a folder keyed to one would be orphaned the
+ * day it does. Ids are opaque, so the name carries no PII into git history
+ * (which this platform never rewrites). `branchSegment` is THE segment
+ * sanitizer — the id lands in the folder name exactly as it lands in the
+ * user's suggestion-branch names, so the two spellings can never disagree.
+ */
+export function personalGroupFolderName(userId) {
+    return `${PERSONAL_GROUP_PREFIX}${branchSegment(userId)}`;
+}
+/** Whether a `Groups/` child is somebody's personal folder. */
+export function isPersonalGroupFolder(folderName) {
+    return folderName.startsWith(PERSONAL_GROUP_PREFIX);
+}
+/**
+ * The group a repo-root-relative path belongs to, or `null` for content that
+ * sits outside any group.
+ *
+ *   Groups/GTM/heyreach-campaign/SKILL.md → 'GTM'
+ *   Groups/GTM/heyreach.tool              → 'GTM'
+ *   Groups/loose-skill/SKILL.md           → null    (no group folder)
+ *   KnowledgeBase/Product/…               → null    (not a group root)
+ *
+ * Returns null rather than throwing because a group is a property SOME paths
+ * have. Callers bucket by it; nothing requires it. An ungrouped skill is a
+ * real, supported state — the prototype calls those "yours alone".
  */
-export const TOOLS_DIR = 'Tools';
+export function groupOfPath(repoRelativePath) {
+    const segments = repoRelativePath.split('/').filter(Boolean);
+    if (segments[0] !== GROUPS_DIR)
+        return null;
+    // Needs a segment for the group AND at least one below it, otherwise
+    // `Groups/GTM` (the folder itself) would report itself as being in a group,
+    // and a loose `Groups/slack.tool` would report a group named "slack.tool".
+    return segments.length >= 3 ? (segments[1] ?? null) : null;
+}
 /**
  * Folder under the repo root for agent-produced records (pipeline instances,
  * work items, intermediate outputs). Parsed exactly like `KnowledgeBase/`:

package/dist/workspace/kb-layout.js.map

@@ -1 +1 @@
-{"version":3,"file":"kb-layout.js","sourceRoot":"","sources":["../../src/workspace/kb-layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,oEAAoE;AACpE,MAAM,CAAC,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAElD,qFAAqF;AACrF,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,OAAO,CAAC;AAEjC;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE/B,0GAA0G;AAC1G,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAC;AAEnC,6GAA6G;AAC7G,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC;AAEzC;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAsB,CAAC,kBAAkB,EAAE,QAAQ,CAAC,CAAC;AAEhF,gFAAgF;AAChF,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC;AAEzC,qFAAqF;AACrF,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC;AAExC,+EAA+E;AAC/E,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC,CAAC;AAUvE,8EAA8E;AAC9E,+EAA+E;AAC/E,2EAA2E;AAC3E,uEAAuE"}
+{"version":3,"file":"kb-layout.js","sourceRoot":"","sources":["../../src/workspace/kb-layout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,oEAAoE;AACpE,MAAM,CAAC,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAElD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAC;AAEnC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,WAAW,CAAC;AAEjD;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAc;IACpD,OAAO,GAAG,qBAAqB,GAAG,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;AAC5D,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,qBAAqB,CAAC,UAAkB;IACtD,OAAO,UAAU,CAAC,UAAU,CAAC,qBAAqB,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,gBAAwB;IAClD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC7D,IAAI,QAAQ,CAAC,CAAC,CAAC,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IAC5C,qEAAqE;IACrE,4EAA4E;IAC5E,2EAA2E;IAC3E,OAAO,QAAQ,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7D,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE/B,0GAA0G;AAC1G,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAC;AAEnC,6GAA6G;AAC7G,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC;AAEzC;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAsB,CAAC,kBAAkB,EAAE,QAAQ,CAAC,CAAC;AAEhF,gFAAgF;AAChF,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC;AAEzC,qFAAqF;AACrF,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC;AAExC,+EAA+E;AAC/E,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC,CAAC;AAUvE,8EAA8E;AAC9E,+EAA+E;AAC/E,2EAA2E;AAC3E,uEAAuE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-shared",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Shared types and pure domain utilities of the Bevel core platform (auth, workspace, git/workflow contracts, branch registry).",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,7 +14,8 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "THIRD-PARTY-NOTICES.md"
   ],
   "engines": {
     "node": ">=22 <23"
@@ -28,7 +29,7 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Bevel-Software/skill-and-tool-management.git",
+    "url": "git+https://github.com/Bevel-Software/Hexis.git",
     "directory": "packages/shared"
   },
   "publishConfig": {

package/src/auth/types.ts

@@ -1,16 +1,24 @@
-export interface AuthUser {
-  id: string;
-  email: string;
-  name: string;
-  avatarUrl?: string;
-}
-
-export interface LoginRequest {
-  email: string;
-  password: string;
-}
-
-export interface LoginResponse {
-  token: string;
-  user: AuthUser;
-}
+export interface AuthUser {
+  id: string;
+  email: string;
+  name: string;
+  avatarUrl?: string;
+  /**
+   * Has this person concluded the connect-your-agent onboarding (welcome
+   * page Done, or dismissing the reminder pill). Optional so pre-existing
+   * fixtures and cached user objects stay valid; the server always sends it,
+   * and consumers treat only an explicit `false` as "still onboarding" — an
+   * absent field must never resurrect the welcome flow.
+   */
+  onboardingDone?: boolean;
+}
+
+export interface LoginRequest {
+  email: string;
+  password: string;
+}
+
+export interface LoginResponse {
+  token: string;
+  user: AuthUser;
+}

package/src/git/branchAuthor.ts

@@ -44,3 +44,40 @@ export function isBranchAuthoredBy(
   if (!localpart) return false;
   return branchName.startsWith(`${localpart}/`);
 }
+
+/** Keep only characters git branch segments accept; collapse the rest to '-'. */
+export function branchSegment(raw: string): string {
+  const cleaned = raw
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^[-.]+/, '')
+    .replace(/[.]+$/, '');
+  return cleaned || 'user';
+}
+
+/**
+ * The `suggestions/<who>-<id8>/` prefix every one of this user's suggestion
+ * branches carries (`…/knowledge` for the Knowledge bundle, a skill segment
+ * for skill proposals). SHARED so the client that names the branch and the
+ * server that judges "may this caller delete it" can never disagree. The
+ * user-id slice is what makes the identity collision-proof — `branchSegment`
+ * alone is lossy (`alex+ops@…` and `alex-ops@…` both clean to `alex-ops`).
+ */
+export function suggestionsBranchPrefixFor(user: { email: string; id: string }): string {
+  const who = branchSegment(user.email.split('@')[0]);
+  const id = branchSegment(user.id).slice(0, 8) || 'user';
+  return `suggestions/${who}-${id}/`;
+}
+
+/**
+ * True when `branchName` is one of THIS user's suggestion branches — the
+ * authorship rule for the `suggestions/…` namespace, where the plain
+ * `<localpart>/` convention of {@link isBranchAuthoredBy} does not apply.
+ */
+export function isOwnSuggestionsBranch(
+  branchName: string,
+  user: { email: string | null | undefined; id: string | null | undefined },
+): boolean {
+  if (!user.email || !user.id) return false;
+  return branchName.startsWith(suggestionsBranchPrefixFor({ email: user.email, id: user.id }));
+}

package/src/git/protected.ts

@@ -1,40 +1,24 @@
 /**
- * Authoritative, env-overridable registry of the default branch + the set of
- * protected branch slugs in the KB repo, plus their user-visible display names.
+ * The default branch + the set of protected branch slugs in the KB repo, and
+ * their user-visible display names. Single source of truth for BOTH sides of
+ * the app, so backend enforcement and frontend affordances can never drift.
  *
- * Single source of truth for BOTH sides of the app:
- *  - Backend (Node) reads `process.env.*` at runtime — the values are populated
- *    from the environment / the `.env` loaded by `config.ts`, which runs before
- *    this module is first evaluated (see `backend/src/index.ts` import order).
- *  - Frontend (browser) can't read `process.env` at runtime, so Vite statically
- *    replaces the `process.env.DEFAULT_BRANCH` / `process.env.PROTECTED_BRANCHES`
- *    references at build time via `define` in `frontend/vite.config.ts`. Keep
- *    those references written as the literal `process.env.<NAME>` member access
- *    so the static replacement keeps matching.
+ * CONFIGURED, NOT IMPORTED. This module used to read `process.env` at import
+ * time and throw when it found nothing — which made the branch model something
+ * a deployment had to know before any code could load. On the frontend that
+ * meant baking it into the bundle at build time (Vite `define`), so the same
+ * artifact could not serve two deployments and changing a branch name meant a
+ * rebuild. Both sides now CALL {@link configureBranchModel} during boot:
+ * the backend from its environment, the browser from `GET /api/config`.
  *
- * Both the backend (server-side enforcement — refusing commit/push/revert and
- * rejecting `createBranch` on protected names) and the frontend (disabling UI
- * actions, showing the protected-branch banner, branch sort order) consume this
- * single table so the two can never drift. Don't re-declare or hard-code the
- * names elsewhere.
- *
- * Env vars (both REQUIRED — no fallback; the module throws at load if either is
- * missing/empty, so a misconfigured deploy fails fast instead of silently
- * defaulting to the wrong branches). Note the frontend needs them present at
- * BUILD time (Vite `define`), the backend at runtime:
- *  - `DEFAULT_BRANCH`      — the branch a user lands on / the default propose
- *                            target.
- *  - `PROTECTED_BRANCHES`  — comma/space-separated list of protected slugs.
- *                            Display names are auto-derived from each slug
- *                            (`target-company-state` → "Target company state").
+ * The exported bindings stay bindings — `DEFAULT_BRANCH` is still imported and
+ * read exactly as before at every call site. ES module live bindings mean a
+ * reader inside a function body sees whatever configuration has been applied by
+ * the time it runs. What does NOT work is capturing one at module scope
+ * (`const X = DEFAULT_BRANCH` in a file's top level), which snapshots the value
+ * at import — before configuration. Use a function there instead.
  */
 
-// `process` is supplied by Node at runtime on the backend and statically
-// replaced by Vite at build time on the frontend (vite.config.ts `define`).
-// Declared locally — narrowed to just `env` — so this shared module typechecks
-// without pulling @types/node into the @bevel-software/platform-shared package. On the backend
-// build (which has @types/node) this module-scoped declaration simply shadows
-// the global `process`, which is harmless here.
 declare const process: { env: Record<string, string | undefined> };
 
 function parseBranchList(raw: string | undefined): string[] {
@@ -57,42 +41,89 @@ function deriveDisplayName(slug: string): string {
 
 /**
  * The branch a logged-in user lands on when they don't explicitly pick one, and
- * the default destination for shared drafts. Env-overridable via `DEFAULT_BRANCH`.
+ * the default destination for shared drafts.
+ *
+ * Empty until {@link configureBranchModel} runs. Read it inside a function, not
+ * at module scope — see this file's header.
  */
-export const DEFAULT_BRANCH: string = (process.env.DEFAULT_BRANCH ?? '').trim();
-if (!DEFAULT_BRANCH) {
-  throw new Error(
-    'DEFAULT_BRANCH env var is required (no fallback). Set it on the backend ' +
-      'runtime and at the frontend build (Vite reads it via define).',
-  );
+export let DEFAULT_BRANCH: string = '';
+
+export let PROTECTED_BRANCH_DISPLAY_NAMES: Readonly<Record<string, string>> = Object.freeze({});
+
+export let PROTECTED_BRANCHES: ReadonlySet<string> = new Set<string>();
+
+/** The shape both sides configure from, and the shape `/api/config` serves. */
+export interface BranchModel {
+  defaultBranch: string;
+  /** Slugs; a comma/space-separated string is accepted for env convenience. */
+  protectedBranches: string[] | string;
 }
 
-const PROTECTED_BRANCH_LIST: string[] = parseBranchList(process.env.PROTECTED_BRANCHES);
-if (PROTECTED_BRANCH_LIST.length === 0) {
-  throw new Error(
-    'PROTECTED_BRANCHES env var is required (no fallback). Provide a ' +
-      'comma/space-separated list of protected branch slugs.',
-  );
+/**
+ * Apply the branch model. Called once during boot on each side, and validated
+ * here rather than at either call site so the two cannot disagree about what
+ * counts as a valid pair.
+ */
+export function branchListOf(model: BranchModel): string[] {
+  return Array.isArray(model.protectedBranches)
+    ? model.protectedBranches.map((s) => s.trim()).filter(Boolean)
+    : parseBranchList(model.protectedBranches);
 }
-// The default branch is where users land and the default propose target — it
-// must itself be protected, or `isProtectedBranch(DEFAULT_BRANCH)` is false and
-// the protected-branch guards silently don't apply to it. Fail fast on a
-// misconfigured pair rather than shipping that inconsistency.
-if (!PROTECTED_BRANCH_LIST.includes(DEFAULT_BRANCH)) {
-  throw new Error(
-    `DEFAULT_BRANCH ("${DEFAULT_BRANCH}") must be one of PROTECTED_BRANCHES ` +
-      `(${PROTECTED_BRANCH_LIST.join(', ')}).`,
-  );
+
+/**
+ * What is wrong with a pair, or null when nothing is — the same rule
+ * {@link configureBranchModel} enforces, without applying anything.
+ *
+ * Separate because the setup screen has to VALIDATE a proposed pair before it
+ * is saved, and applying a model as a side effect of checking it would swap the
+ * running app onto branches nobody has confirmed yet.
+ */
+export function validateBranchModel(model: BranchModel): string | null {
+  const defaultBranch = (model.defaultBranch ?? '').trim();
+  const list = branchListOf(model);
+  if (!defaultBranch) return 'A default branch is required — the branch users land on.';
+  if (list.length === 0) return 'At least one protected branch is required.';
+  // The default branch is where users land and the default propose target — it
+  // must itself be protected, or `isProtectedBranch(DEFAULT_BRANCH)` is false
+  // and the protected-branch guards silently do not apply to it. Refuse the
+  // pair rather than ship that inconsistency.
+  if (!list.includes(defaultBranch)) {
+    return (
+      `The default branch ("${defaultBranch}") must be one of the protected branches ` +
+      `(${list.join(', ')}).`
+    );
+  }
+  return null;
 }
 
-export const PROTECTED_BRANCH_DISPLAY_NAMES: Readonly<Record<string, string>> =
-  Object.freeze(
-    Object.fromEntries(
-      PROTECTED_BRANCH_LIST.map((slug) => [slug, deriveDisplayName(slug)]),
-    ),
+export function configureBranchModel(model: BranchModel): void {
+  const problem = validateBranchModel(model);
+  if (problem) throw new Error(problem);
+  const defaultBranch = model.defaultBranch.trim();
+  const list = branchListOf(model);
+
+  DEFAULT_BRANCH = defaultBranch;
+  PROTECTED_BRANCH_DISPLAY_NAMES = Object.freeze(
+    Object.fromEntries(list.map((slug) => [slug, deriveDisplayName(slug)])),
   );
+  PROTECTED_BRANCHES = new Set(list);
+}
 
-export const PROTECTED_BRANCHES: ReadonlySet<string> = new Set(PROTECTED_BRANCH_LIST);
+/** Whether {@link configureBranchModel} has run — the frontend gates render on this. */
+export function isBranchModelConfigured(): boolean {
+  return DEFAULT_BRANCH !== '';
+}
+
+/**
+ * The model as the environment describes it. Node-side only; the browser has no
+ * `process.env` to read and is served the same shape by `GET /api/config`.
+ */
+export function branchModelFromEnv(): BranchModel {
+  return {
+    defaultBranch: (process.env.DEFAULT_BRANCH ?? '').trim(),
+    protectedBranches: process.env.PROTECTED_BRANCHES ?? '',
+  };
+}
 
 export function isProtectedBranch(name: string | null | undefined): boolean {
   return !!name && Object.prototype.hasOwnProperty.call(