@bevel-software/platform-shared 0.15.1 → 0.20.0

package/dist/workspace/frontmatter.js

@@ -1,15 +1,62 @@
+/**
+ * THE fence rule: a line is a frontmatter fence when, whitespace aside, it is
+ * exactly `---`. Forgiving on purpose — an opening fence with a trailing space
+ * or an indented fence is still a fence.
+ *
+ * Every reader in the platform asks this one function. The access model's
+ * line scan always judged fences this way while the splitter below demanded
+ * `---` at column 0, so a file written with a near-miss fence had access
+ * rules that applied while the catalog, the tool manuals and the frontmatter
+ * panel saw no frontmatter at all. One rule, asked everywhere, is what keeps
+ * a file from meaning two things.
+ */
+export function isFrontmatterFence(line) {
+    return line?.trim() === '---';
+}
 /**
  * The ONE `---` frontmatter splitter, shared by backend and frontend so no file
- * type grows its own regex. Splits a leading `---`-fenced YAML block from the
- * body; null when the text doesn't open with a fence. Parsing the YAML inside is
- * the caller's concern (the access-control resolver deliberately keeps its own
- * hardened line-based reader — see `modules/access/access-splice.ts`).
+ * type grows its own reader. Splits a leading fenced YAML block from the body;
+ * null when the first line is not a fence or no later line closes it. Fences
+ * are judged by {@link isFrontmatterFence}. Parsing the YAML inside is the
+ * caller's concern (the access model keeps its own line scan, on the same
+ * fence rule, because a splice must put bytes back exactly as it found them).
+ *
+ * `frontmatter` is the raw text between the fence lines and `body` the raw
+ * text after the closing fence's line break, both byte for byte — line
+ * endings included — so a caller that rebuilds the file changes nothing it
+ * did not mean to.
  */
 export function extractFrontmatter(text) {
-    const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
-    if (!m)
-        return null;
-    return { frontmatter: m[1], body: m[2] };
+    // Walk the lines by offset rather than splitting, so both halves can be
+    // sliced out of the original text with their own line endings intact.
+    let start = 0;
+    let lineIndex = 0;
+    let openEnd = -1; // offset just past the opening fence's line break
+    while (start <= text.length) {
+        const nl = text.indexOf('\n', start);
+        const end = nl === -1 ? text.length : nl;
+        const line = text.slice(start, end).replace(/\r$/, '');
+        const next = nl === -1 ? text.length + 1 : nl + 1;
+        if (lineIndex === 0) {
+            // A lone `---` with nothing after it opens nothing.
+            if (!isFrontmatterFence(line) || nl === -1)
+                return null;
+            openEnd = next;
+        }
+        else if (isFrontmatterFence(line)) {
+            // The frontmatter ends before the line break that precedes this fence.
+            const fmEnd = start - (start >= 2 && text[start - 2] === '\r' ? 2 : 1);
+            return {
+                frontmatter: fmEnd > openEnd ? text.slice(openEnd, fmEnd) : '',
+                body: next > text.length ? '' : text.slice(next),
+            };
+        }
+        if (nl === -1)
+            return null; // never closed
+        start = next;
+        lineIndex += 1;
+    }
+    return null;
 }
 /**
  * Set a top-level scalar key in a file's `---` frontmatter, LINE-based: replace an
@@ -37,7 +84,10 @@ export function setFrontmatterField(text, key, value) {
         // No frontmatter — prepend a fresh block, keeping the original body intact.
         return `---${eol}${line}${eol}---${eol}${text}`;
     }
-    const fmLines = fm.frontmatter.split(/\r?\n/);
+    // An empty block has no lines, not one empty line: splitting '' would give
+    // [''], and the inserted key would be followed by a blank line before the
+    // closing fence.
+    const fmLines = fm.frontmatter === '' ? [] : fm.frontmatter.split(/\r?\n/);
     const idx = fmLines.findIndex((l) => keyRe.test(l));
     if (idx >= 0)
         fmLines[idx] = line;

package/dist/workspace/frontmatter.js.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../src/workspace/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACpE,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC3C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY,EAAE,GAAW,EAAE,KAAa;IAC1E,MAAM,EAAE,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,GAAG,GAAG,KAAK,KAAK,EAAE,CAAC;IAChC,8EAA8E;IAC9E,0EAA0E;IAC1E,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,UAAU,GAAG,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACrF,8EAA8E;IAC9E,2EAA2E;IAC3E,2EAA2E;IAC3E,4EAA4E;IAC5E,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,GAAG,GAAG,OAAO,GAAG,CAAC,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IACtE,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,4EAA4E;QAC5E,OAAO,MAAM,GAAG,GAAG,IAAI,GAAG,GAAG,MAAM,GAAG,GAAG,IAAI,EAAE,CAAC;IAClD,CAAC;IACD,MAAM,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,GAAG,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;;QAC7B,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,MAAM,GAAG,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC;AAClE,CAAC"}
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../src/workspace/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAwB;IACzD,OAAO,IAAI,EAAE,IAAI,EAAE,KAAK,KAAK,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,wEAAwE;IACxE,sEAAsE;IACtE,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,kDAAkD;IACpE,OAAO,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAC5B,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACrC,MAAM,GAAG,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACvD,MAAM,IAAI,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAClD,IAAI,SAAS,KAAK,CAAC,EAAE,CAAC;YACpB,oDAAoD;YACpD,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC;YACxD,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;aAAM,IAAI,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;YACpC,uEAAuE;YACvE,MAAM,KAAK,GAAG,KAAK,GAAG,CAAC,KAAK,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACvE,OAAO;gBACL,WAAW,EAAE,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE;gBAC9D,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;aACjD,CAAC;QACJ,CAAC;QACD,IAAI,EAAE,KAAK,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC,CAAC,eAAe;QAC3C,KAAK,GAAG,IAAI,CAAC;QACb,SAAS,IAAI,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY,EAAE,GAAW,EAAE,KAAa;IAC1E,MAAM,EAAE,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,GAAG,GAAG,KAAK,KAAK,EAAE,CAAC;IAChC,8EAA8E;IAC9E,0EAA0E;IAC1E,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,UAAU,GAAG,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACrF,8EAA8E;IAC9E,2EAA2E;IAC3E,2EAA2E;IAC3E,4EAA4E;IAC5E,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,GAAG,GAAG,OAAO,GAAG,CAAC,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IACtE,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,4EAA4E;QAC5E,OAAO,MAAM,GAAG,GAAG,IAAI,GAAG,GAAG,MAAM,GAAG,GAAG,IAAI,EAAE,CAAC;IAClD,CAAC;IACD,2EAA2E;IAC3E,0EAA0E;IAC1E,iBAAiB;IACjB,MAAM,OAAO,GAAG,EAAE,CAAC,WAAW,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC3E,MAAM,GAAG,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;;QAC7B,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,MAAM,GAAG,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC;AAClE,CAAC"}

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

@@ -96,14 +96,133 @@ export declare let SKILLS_DIR: string;
  * manifest's `name` field.
  */
 export declare let PLUGINS_DIR: string;
-/** The three renameable roots, as a deployment declares them and `/api/config` serves them. */
+/**
+ * The file name of the platform's MANAGED agent guide at the repository root —
+ * the document every connected agent is told to read first, written and
+ * refreshed from the packaged template on every start.
+ *
+ * Configurable for one reason: `AGENTS.md` is the name coding agents look for
+ * by convention, so a customer arriving with a repository of their own very
+ * often already HAS one, and under the default name the platform would
+ * overwrite it on the first boot and on every boot after. Renaming the managed
+ * guide (`HEXIS.md`, say) hands that name back: `AGENTS.md` becomes ordinary
+ * content the platform never writes, never refreshes and never hides, and the
+ * customer's file is the one that points at ours (see
+ * {@link agentsFilePointerSentence}).
+ *
+ * A live binding like the three roots above — read it inside a function body,
+ * never capture it at module scope.
+ */
+export declare let AGENTS_FILE: string;
+/**
+ * The name the managed guide had when it was the only name it could have.
+ *
+ * Referenced ONLY by the code that has to tell OUR file from THEIRS — the
+ * boot-time removal of a platform-written `AGENTS.md`, the ignore rule that
+ * stops hiding it, the instruction telling an agent to read the customer's
+ * file too. In the spirit of {@link LEGACY_GROUPS_DIR}: a second live spelling
+ * of the CURRENT name is how two layouts start being supported by accident, so
+ * this one is a constant and means exactly one thing.
+ */
+export declare const LEGACY_AGENTS_FILE = "AGENTS.md";
+/**
+ * The platform files whose names are FIXED — the ones no deployment renames.
+ * The guide is the fourth platform file and is deliberately absent here: its
+ * name is {@link AGENTS_FILE}, and `platform-files.ts` composes the two into
+ * the set every gate reads.
+ *
+ * It lives in this module rather than beside that composition because the
+ * LAYOUT has to validate against it (a guide may not be called `access.md`),
+ * and `platform-files.ts` already reads this module — the other direction
+ * would be a cycle.
+ */
+export declare const FIXED_PLATFORM_FILE_NAMES: readonly string[];
+/**
+ * The three renameable roots and the guide's file name, as a deployment
+ * declares them and `/api/config` serves them.
+ */
 export interface KbLayout {
     knowledgeBaseDir: string;
     skillsDir: string;
     pluginsDir: string;
+    /**
+     * The managed agent guide's file name. OPTIONAL, and deliberately: a layout
+     * that predates the setting — an older server's `/api/config` body, a saved
+     * deployment that never named one — carries three folders and no guide, and
+     * the right answer to that is the right answer to an unset field, which is
+     * `AGENTS.md`. Read it through {@link agentsFileOf} rather than directly, so
+     * "absent" and "the default" can never come to mean two different things.
+     */
+    agentsFile?: string;
 }
 /** The layout a deployment gets when it names nothing. */
-export declare const DEFAULT_KB_LAYOUT: Readonly<KbLayout>;
+export declare const DEFAULT_KB_LAYOUT: Readonly<Required<KbLayout>>;
+/** The guide's name in a layout, with the default standing in for an absent one. */
+export declare function agentsFileOf(layout: KbLayout): string;
+/**
+ * `name` as one literal gitignore pattern. The guide's name is the
+ * operator's, and the name rules admit characters gitignore reads as syntax:
+ * a leading `#` is a comment and a leading `!` a negation (the rule would
+ * silently hide nothing), `[`, `]`, `*` and `?` are globs, and a backslash is
+ * the escape itself. Each is escaped so the pattern names exactly the file.
+ */
+export declare function gitignoreLiteral(name: string): string;
+/**
+ * The ONE sentence the platform offers to keep in a customer's own
+ * `AGENTS.md`, pointing at the managed guide beside it.
+ *
+ * Defined here, once, because two surfaces must produce the identical text:
+ * the deployment-settings field previews it before the admin consents, and the
+ * startup step appends it. A sentence written twice is a sentence that drifts,
+ * and a drifted one appends a SECOND copy to every customer file on the boot
+ * after the drift — which is the one thing this whole feature exists to stop.
+ *
+ * A guide name is a FILE NAME, not an identifier: everything `validateFilename`
+ * admits can appear in it — spaces, brackets, parentheses, `#`, `%` — and each
+ * of those means something in an inline link. So the link is BUILT rather than
+ * interpolated: the label backslash-escaped ({@link markdownLinkLabel}), the
+ * destination percent-encoded ({@link agentsFileLinkPath}). A name that only
+ * parenthesised would break the destination; `#` would turn the rest of the
+ * name into a URL fragment, and the link would point at the customer's own
+ * file.
+ *
+ * Neither spelling need match the name as it is on disk, so nothing may ask
+ * whether this sentence is present by searching for the RAW name — see
+ * {@link mentionsAgentsFile}, which is how the startup step asks.
+ */
+export declare function agentsFilePointerSentence(agentsFile?: string): string;
+/**
+ * `text` with every pointer sentence THE PLATFORM WROTE aimed at `agentsFile`
+ * — or null when it holds none of ours.
+ *
+ * This is what a SECOND rename needs. The guide's name is a setting an admin
+ * may change again: a knowledge base whose `AGENTS.md` was given a sentence
+ * pointing at `HEXIS.md` and is then renamed to `GUIDE.md` must have that
+ * sentence aimed at the new file, not a second one appended beneath a first
+ * that now points at nothing. Asking only whether the NEW name is mentioned
+ * cannot see that — the old sentence does not mention it.
+ *
+ * Returning the text unchanged (rather than null) when the sentence is already
+ * right is deliberate: "ours and correct" and "not ours at all" are different
+ * answers, and only the caller knows that the second one means "consider
+ * appending".
+ */
+export declare function retargetAgentsFilePointer(text: string, agentsFile?: string): string | null;
+/**
+ * Whether `text` already points at the guide — the ONE question the startup
+ * step asks before appending {@link agentsFilePointerSentence} to a customer's
+ * own `AGENTS.md`.
+ *
+ * The plain name is the answer that matters: a mention in the customer's own
+ * words, a heading, a link they wrote, all count, and the platform stays out
+ * of a file it does not own. The other two spellings are the platform's OWN,
+ * and they are here for idempotence: the sentence writes the name escaped in
+ * the label and encoded in the destination, so on a punctuated name the file
+ * the last boot wrote need not contain the raw name at all. Asking only for
+ * that one would append a second copy on the next boot, and a third on the
+ * one after — the exact failure this feature exists to prevent.
+ */
+export declare function mentionsAgentsFile(text: string, agentsFile?: string): boolean;
 /**
  * What is wrong with one root name, or null. A root is joined onto the repo
  * root and onto `<dir>/.gitkeep`, so a separator or `..` would write outside
@@ -111,14 +230,60 @@ export declare const DEFAULT_KB_LAYOUT: Readonly<KbLayout>;
  * treats dot-entries as bookkeeping; `.git` in any case would corrupt the clone.
  */
 export declare function validateKbRootName(name: string): string | null;
+/**
+ * What is wrong with the agent guide's file name, or null.
+ *
+ * The rules, and what each one is for:
+ *
+ *  - ONE FILE NAME. The name is joined onto the repository root and read from
+ *    there and nowhere else, so a separator would name a file the platform
+ *    would write but never read back.
+ *  - A MARKDOWN NAME. The guide is a markdown document that people open in the
+ *    app and agents read as text; `.md` is also what the per-file access rules
+ *    apply to, so a guide under any other extension would take its folder's
+ *    rules and stop being readable by everyone.
+ *  - NOT `CLAUDE.md`. That is the guide's own pre-rename name; knowledge bases
+ *    seeded before the rename still carry one, and it stays legacy content
+ *    rather than becoming a second managed file.
+ *  - NOT ANOTHER PLATFORM FILE. Two platform roles on one path means whichever
+ *    writer runs last wins, silently.
+ *  - NOT A ROOT FOLDER'S NAME, compared case-insensitively like the roots are
+ *    to each other: the workspaces live on case-insensitive filesystems, where
+ *    a file `Docs.md` and a folder `docs.md` are one entry.
+ *
+ * `roots` is the layout the name is judged against — the names this save would
+ * put in effect, not necessarily the ones running now.
+ */
+export declare function validateAgentsFileName(name: string, roots?: Pick<KbLayout, 'knowledgeBaseDir' | 'skillsDir' | 'pluginsDir'>): string | null;
 /**
  * What is wrong with a layout, or null — the same rule {@link configureKbLayout}
  * enforces, without applying anything. Separate so the setup screen can judge a
- * proposed layout before it is saved. The three names must differ, compared
- * case-insensitively: the workspaces live on case-insensitive filesystems too,
- * where `Skills` and `skills` are one folder.
+ * proposed layout before it is saved. The three folder names must differ,
+ * compared case-insensitively: the workspaces live on case-insensitive
+ * filesystems too, where `Skills` and `skills` are one folder. The guide's
+ * file name is judged against all three by the same rule (see
+ * {@link validateAgentsFileName}), which makes the four names distinct.
  */
 export declare function validateKbLayout(layout: KbLayout): string | null;
+/**
+ * Be told when {@link configureKbLayout} runs — for the few things that cannot
+ * read a live binding at the moment they are used.
+ *
+ * Almost nothing needs this: the roots and the guide's name are `let` bindings
+ * read inside function bodies, so code that follows the rule follows the
+ * layout for free. The exception is a value BUILT ONCE and handed to something
+ * that keeps it — the tool catalog's descriptions, which are validated into
+ * frozen-ish defs at registration and then served to agents from a map. Boot
+ * applies the layout before they are built, but the save that completes
+ * FIRST-RUN SETUP applies it afterwards (see `setup.routes.ts`, which must, so
+ * the KB phase that runs in the same request scaffolds the names the admin
+ * just chose) — and without this the catalog would go on naming `AGENTS.md`
+ * until someone restarted the server.
+ *
+ * Listeners run in registration order, after the bindings are updated and only
+ * when the layout was accepted.
+ */
+export declare function onKbLayoutApplied(listener: () => void): void;
 /**
  * Apply the layout. Called once during boot on each side; throws on an invalid
  * one so a bad deployment setting fails beside the rest of the wiring rather
@@ -126,14 +291,24 @@ export declare function validateKbLayout(layout: KbLayout): string | null;
  */
 export declare function configureKbLayout(layout: KbLayout): void;
 /** The layout currently in effect. */
-export declare function currentKbLayout(): KbLayout;
+export declare function currentKbLayout(): Required<KbLayout>;
+/**
+ * Whether a layout — the one in effect, unless one is given — is the default
+ * one. The setup-completing save applies the stored names while this holds,
+ * the same "only from none to some" rule the branch model follows — and also
+ * on a retry after its own failed initialization run, when the process holds
+ * names setup applied but the app never opened (see `setup.routes.ts`). A
+ * layout the process booted with is never replaced here.
+ */
+export declare function isDefaultKbLayout(layout?: KbLayout): boolean;
 /**
  * Render the layout placeholders a managed template carries —
- * `{{knowledgeBaseDir}}`, `{{skillsDir}}`, `{{pluginsDir}}` — with the
- * names in effect. The packaged `AGENTS.md` and `.bevelignore` are written
- * this way so a deployment that renamed its roots hands the agent a guide
- * that names the folders it will actually find. Text without placeholders
- * passes through unchanged.
+ * `{{knowledgeBaseDir}}`, `{{skillsDir}}`, `{{pluginsDir}}`, `{{agentsFile}}`
+ * — with the names in effect. The packaged guide and `.bevelignore` are
+ * written this way so a deployment that renamed its roots hands the agent a
+ * guide that names the folders it will actually find, and a deployment that
+ * renamed the guide gets a guide naming the file it lives in. Text without
+ * placeholders passes through unchanged.
  */
 export declare function renderKbLayoutPlaceholders(text: string, layout?: KbLayout): string;
 /**
@@ -232,17 +407,39 @@ export declare function pluginIdentityOf(manifest: Record<string, unknown> | nul
 /**
  * What a person sees the plugin called: the manifest's `displayName` (the
  * vendor field Claude Code shows in its picker; any casing, spaces allowed),
- * else the folder name — which is what every plugin made before this field
- * existed was called, so nothing renames itself on upgrade.
+ * else the manifest's `name`.
+ *
+ * THE MANIFEST IS THE ONLY SOURCE — there is no folder argument, on purpose.
+ * The folder's spelling used to stand in here, which made where a plugin
+ * happens to live a hidden input to what everyone sees it called: the API
+ * always answered with a display name while the file sometimes omitted the
+ * field, and moving or re-casing a folder silently renamed the plugin. Every
+ * write path now persists the field (see {@link renderPluginManifest} and
+ * the rename service), and one startup step backfilled the folder's spelling
+ * into the manifests written before that, so nothing renames itself.
+ *
+ * Empty only for a manifest that names nothing at all — the shape discovery
+ * already warns about and stands the folder in as the IDENTITY for; its
+ * display name then follows that identity, never the folder directly.
  */
-export declare function pluginDisplayNameOf(manifest: Record<string, unknown> | null, folderName: string): string;
+export declare function pluginDisplayNameOf(manifest: Record<string, unknown> | null): string;
 /**
  * A minimal, valid `plugin.json` for a plugin folder: the identifier the
- * folder name folds into, and — when the folder is spelled differently — the
- * folder's spelling as `displayName`, so a client's picker shows "Sales
- * Team" for `sales-team`. Nothing else: `version`, `license` and the rest
- * are metadata about a DISTRIBUTED package, and inventing values for a
- * folder someone just made in the app would be asserting things nobody said.
+ * folder name folds into, and the name a person sees it by — `displayName`,
+ * ALWAYS written, so a client's picker shows "Sales Team" for `sales-team`
+ * and every reader has the one field to read.
+ *
+ * ONE argument, deliberately: `folderName` is the folder's own leaf, and on
+ * the creation path that leaf IS the name its creator typed, trimmed — the
+ * dialog's route and the `create_plugin` tool make the folder out of the
+ * typed name and hand the same string to both. A second `displayName`
+ * parameter would be a way for the two to disagree that no caller needs.
+ * The field is written even when it equals the identifier: a manifest that
+ * omits it when the two agree is a manifest whose readers need a second rule.
+ *
+ * Nothing else: `version`, `license` and the rest are metadata about a
+ * DISTRIBUTED package, and inventing values for a folder someone just made
+ * in the app would be asserting things nobody said.
  */
 export declare function renderPluginManifest(folderName: string): string;
 /**
@@ -312,6 +509,16 @@ export declare function ontologyRoots(): readonly string[];
  * renders as its own sections rather than folding into Knowledge.
  */
 export declare function reservedRootDirNames(): ReadonlySet<string>;
+/**
+ * The roots anyone may start a new folder in — knowledge, skills and plugins
+ * — whatever the root's own `access.md` grants them. Everywhere else a change
+ * needs read access to where it lands (the "read before write" rule); a new
+ * folder directly under one of these three is the one place that rule does
+ * not apply, because the new folder carries its creator's own grant. A
+ * function, like {@link reservedRootDirNames}, because the names are
+ * configurable.
+ */
+export declare function creatableRootDirNames(): ReadonlySet<string>;
 /** The `Knowledge/` marker subfolder of an ontology (holds the graph nodes). */
 export declare const KNOWLEDGE_DIR = "Knowledge";
 /** The `NodeTypes/` marker subfolder of an ontology (holds the type definitions). */

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":"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"}
+{"version":3,"file":"kb-layout.d.ts","sourceRoot":"","sources":["../../src/workspace/kb-layout.ts"],"names":[],"mappings":"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"}