studiograph 1.3.48-next.13 → 1.3.48-next.130

package/dist/core/entity-body-templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-body-templates.js","sourceRoot":"","sources":["../../src/core/entity-body-templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAA2B;IAC5D,MAAM;IACN,MAAM,EAAW,wBAAwB;IACzC,YAAY,EAAK,4BAA4B;IAC7C,QAAQ,EAAS,wDAAwD;IACzE,IAAI,EAAa,4CAA4C;IAE7D,KAAK;IACL,OAAO,EAAU,gDAAgD;IACjE,KAAK,EAAY,+CAA+C;IAChE,IAAI,EAAa,gCAAgC;IACjD,WAAW,EAAM,yCAAyC;IAE1D,gBAAgB;IAChB,QAAQ,EAAS,+BAA+B;IAChD,IAAI,EAAa,iDAAiD;IAClE,WAAW,EAAM,+CAA+C;IAChE,YAAY,EAAK,0DAA0D;IAC3E,OAAO,EAAU,8FAA8F;IAC/G,wEAAwE;IACxE,uEAAuE;IACvE,sEAAsE;IACtE,4DAA4D;IAC5D,KAAK,EAAY,6OAA6O;IAE9P,UAAU;IACV,SAAS,EAAQ,gCAAgC;CAClD,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,UAAkB;IACvD,OAAO,sBAAsB,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC;AACpD,CAAC"}

package/dist/core/entity-types-catalog.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Curated entity-type catalog for Studiograph.
+ *
+ * The full canonical schema set lives in `validation.ts` (ENTITY_SCHEMAS).
+ * This file exposes two cross-cutting concerns:
+ *
+ * 1. `DEFAULT_BASIC_ENTITY_TYPES` — the small default set every fresh
+ *    workspace surfaces in the New Entry modal's "basic" tier. The tier
+ *    grows for each user as entries of other curated types appear in
+ *    folders that user can access (see the picker in
+ *    web/src/lib/components/entity/NewEntryTypePicker.svelte). There is no
+ *    persistent per-workspace "active set" — visibility is derived from
+ *    graph presence + folder permissions.
+ *
+ * 2. `CURATED_ENTITY_TYPE_DESCRIPTIONS` — short one-line descriptions for
+ *    every canonical type. Used by the agent system prompt, tool reference,
+ *    and the picker's detail pane.
+ *
+ * This module is pure data — no runtime dependencies on Node APIs or Zod —
+ * so it is safe to import from the web bundle via the
+ * `@core/entity-types-catalog` alias.
+ */
+/**
+ * Default "basic" tier for a fresh workspace. Just the three capture
+ * primitives — the answer to "what do you want to create right now?".
+ * Project / person / organization are organizational types that surface
+ * automatically via the presence-based rule the moment someone creates
+ * their first one. The picker augments this default with any curated
+ * types already present in folders the user can access.
+ */
+export declare const DEFAULT_BASIC_ENTITY_TYPES: readonly ["note", "event", "task"];
+export type DefaultBasicEntityType = typeof DEFAULT_BASIC_ENTITY_TYPES[number];
+export declare function isDefaultBasicEntityType(type: string): boolean;
+/**
+ * Notable fields for each canonical type — the ones worth surfacing in the
+ * New Entry picker's detail pane as "what this type captures" chips. Not a
+ * complete field list; that lives in the Zod schemas. Base fields
+ * (entity_type, entity_id, created_at, etc.) are never listed here.
+ *
+ * Labels are Title Case to match the user-facing property panel.
+ */
+export declare const CURATED_ENTITY_TYPE_FIELDS: Record<string, string[]>;
+export declare function getCuratedEntityTypeFields(type: string): readonly string[];
+/**
+ * One-line descriptions for every canonical entity type. Terse on purpose —
+ * full schema detail lives in validation.ts and is available on demand via
+ * the `get_entity_schema` tool.
+ */
+export declare const CURATED_ENTITY_TYPE_DESCRIPTIONS: Record<string, string>;
+/**
+ * The canonical list of curated entity types, in catalog order. Derived
+ * from CURATED_ENTITY_TYPE_DESCRIPTIONS so descriptions and the type list
+ * stay in sync without this module taking a Zod dependency.
+ */
+export declare const CURATED_ENTITY_TYPES: readonly string[];
+export declare function isCuratedEntityType(type: string): boolean;
+export declare function getCuratedEntityTypeDescription(type: string): string | undefined;
+/**
+ * Compute the "basic" tier of entity types for a given user:
+ * defaults ∪ curated types already present in folders the user can access.
+ * `presentTypes` comes from the permission-filtered /api/repos response —
+ * so this helper respects folder access for free. Non-curated types in
+ * `presentTypes` (e.g. workspace custom types) pass through unchanged.
+ */
+export declare function computeBasicEntityTypes(presentTypes: Iterable<string>): string[];

package/dist/core/entity-types-catalog.js

@@ -0,0 +1,136 @@
+/**
+ * Curated entity-type catalog for Studiograph.
+ *
+ * The full canonical schema set lives in `validation.ts` (ENTITY_SCHEMAS).
+ * This file exposes two cross-cutting concerns:
+ *
+ * 1. `DEFAULT_BASIC_ENTITY_TYPES` — the small default set every fresh
+ *    workspace surfaces in the New Entry modal's "basic" tier. The tier
+ *    grows for each user as entries of other curated types appear in
+ *    folders that user can access (see the picker in
+ *    web/src/lib/components/entity/NewEntryTypePicker.svelte). There is no
+ *    persistent per-workspace "active set" — visibility is derived from
+ *    graph presence + folder permissions.
+ *
+ * 2. `CURATED_ENTITY_TYPE_DESCRIPTIONS` — short one-line descriptions for
+ *    every canonical type. Used by the agent system prompt, tool reference,
+ *    and the picker's detail pane.
+ *
+ * This module is pure data — no runtime dependencies on Node APIs or Zod —
+ * so it is safe to import from the web bundle via the
+ * `@core/entity-types-catalog` alias.
+ */
+/**
+ * Default "basic" tier for a fresh workspace. Just the three capture
+ * primitives — the answer to "what do you want to create right now?".
+ * Project / person / organization are organizational types that surface
+ * automatically via the presence-based rule the moment someone creates
+ * their first one. The picker augments this default with any curated
+ * types already present in folders the user can access.
+ */
+export const DEFAULT_BASIC_ENTITY_TYPES = [
+    'note',
+    'event',
+    'task',
+];
+const DEFAULT_BASIC_SET = new Set(DEFAULT_BASIC_ENTITY_TYPES);
+export function isDefaultBasicEntityType(type) {
+    return DEFAULT_BASIC_SET.has(type);
+}
+/**
+ * Notable fields for each canonical type — the ones worth surfacing in the
+ * New Entry picker's detail pane as "what this type captures" chips. Not a
+ * complete field list; that lives in the Zod schemas. Base fields
+ * (entity_type, entity_id, created_at, etc.) are never listed here.
+ *
+ * Labels are Title Case to match the user-facing property panel.
+ */
+export const CURATED_ENTITY_TYPE_FIELDS = {
+    // CRM
+    person: ['Name', 'Role', 'Category', 'Status', 'Email', 'Location', 'Organization'],
+    organization: ['Name', 'Category', 'Status', 'Industry', 'Website'],
+    position: ['Name', 'Department', 'Category', 'Status'],
+    deal: ['Name', 'Client', 'Contact', 'Stage', 'Deal value', 'Expected close'],
+    // PM
+    project: ['Name', 'Category', 'Project type', 'Client', 'Services', 'Status', 'Start date', 'End date'],
+    event: ['Name', 'Type', 'Date', 'Attendees', 'Location'],
+    task: ['Name', 'Status', 'Priority', 'Assignee', 'Phase', 'Start date', 'Due date'],
+    deliverable: ['Name', 'Project', 'Status', 'Phase', 'Start date', 'Due date'],
+    // KM — authored
+    document: ['Name', 'Category', 'Status'],
+    deck: ['Name', 'Audience', 'Status', 'Presentation date'],
+    publication: ['Name', 'Platform', 'Status', 'URL'],
+    'case-study': ['Name', 'Client', 'Services', 'Date range', 'Status'],
+    service: ['Name', 'Service id', 'Sprint', 'Depends on', 'Enables', 'Deliverables', 'Status'],
+    skill: ['Name', 'Description', 'Applies to'],
+    // Capture
+    note: ['Name'],
+    reference: ['Name', 'Source', 'Link'],
+    // System
+    asset: ['Name', 'Asset kind', 'Size', 'Pages (PDF)'],
+};
+export function getCuratedEntityTypeFields(type) {
+    return CURATED_ENTITY_TYPE_FIELDS[type] ?? [];
+}
+/**
+ * One-line descriptions for every canonical entity type. Terse on purpose —
+ * full schema detail lives in validation.ts and is available on demand via
+ * the `get_entity_schema` tool.
+ */
+export const CURATED_ENTITY_TYPE_DESCRIPTIONS = {
+    // CRM
+    person: 'An individual — team member, client, or contact',
+    organization: 'A company, client, vendor, or partner',
+    position: 'A role or job description',
+    deal: 'A pre-project sales opportunity',
+    // PM
+    project: 'A client engagement or internal initiative',
+    event: 'A meeting, call, workshop, or other gathering',
+    task: 'An action item or to-do',
+    deliverable: 'A scoped output promised to a client',
+    // KM — authored
+    document: 'A proposal, contract, brief, memo, or report',
+    deck: 'A presentation or slide deck',
+    publication: 'Content published externally',
+    'case-study': 'A portfolio narrative',
+    service: 'An offering or methodology your team provides',
+    skill: 'Reusable agent instructions',
+    // Capture
+    note: 'A freeform note or thought',
+    reference: 'An external resource or piece of inspiration',
+    // System
+    asset: 'A hosted binary file (PDF, image, video, spreadsheet, etc.) with a wrapper entity for tagging and search',
+};
+/**
+ * The canonical list of curated entity types, in catalog order. Derived
+ * from CURATED_ENTITY_TYPE_DESCRIPTIONS so descriptions and the type list
+ * stay in sync without this module taking a Zod dependency.
+ */
+export const CURATED_ENTITY_TYPES = Object.freeze(Object.keys(CURATED_ENTITY_TYPE_DESCRIPTIONS));
+const CURATED_ENTITY_TYPES_SET = new Set(CURATED_ENTITY_TYPES);
+export function isCuratedEntityType(type) {
+    return CURATED_ENTITY_TYPES_SET.has(type);
+}
+export function getCuratedEntityTypeDescription(type) {
+    return CURATED_ENTITY_TYPE_DESCRIPTIONS[type];
+}
+/**
+ * Compute the "basic" tier of entity types for a given user:
+ * defaults ∪ curated types already present in folders the user can access.
+ * `presentTypes` comes from the permission-filtered /api/repos response —
+ * so this helper respects folder access for free. Non-curated types in
+ * `presentTypes` (e.g. workspace custom types) pass through unchanged.
+ */
+export function computeBasicEntityTypes(presentTypes) {
+    const set = new Set(DEFAULT_BASIC_ENTITY_TYPES);
+    // Include every present type so workspace custom types also surface in
+    // the basic tier once they have at least one entry. Whitespace-only
+    // values are treated as absent — they can sneak in from stale API
+    // responses or test fixtures and would pollute the picker otherwise.
+    for (const t of presentTypes) {
+        if (t && t.trim().length > 0)
+            set.add(t);
+    }
+    return Array.from(set);
+}
+//# sourceMappingURL=entity-types-catalog.js.map

package/dist/core/entity-types-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-types-catalog.js","sourceRoot":"","sources":["../../src/core/entity-types-catalog.ts"],"names":[],"mappings":"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"}

package/dist/core/feature-flags.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Feature flag types and defaults.
+ *
+ * This module is pure data — no runtime dependencies on `process` or Node APIs —
+ * so it can be safely imported from the web bundle (see web/svelte.config.js alias).
+ *
+ * Runtime parsing lives in ./features.ts. Keep them in sync.
+ */
+export declare const FEATURE_ENV_VARS: {
+    readonly meetingCapture: "FEATURE_MEETING_CAPTURE";
+};
+export type FeatureName = keyof typeof FEATURE_ENV_VARS;
+export interface FeatureFlags {
+    /**
+     * Meeting capture (Electron bridge, transcription, recording UI). Default
+     * is now `true` — the feature is GA. The flag is retained as a kill-switch
+     * (set `FEATURE_MEETING_CAPTURE=false` to opt out at the server level), but
+     * none of the application code paths still gate on it.
+     */
+    meetingCapture: boolean;
+}
+export declare const DEFAULT_FEATURE_FLAGS: FeatureFlags;

package/dist/core/feature-flags.js

@@ -0,0 +1,15 @@
+/**
+ * Feature flag types and defaults.
+ *
+ * This module is pure data — no runtime dependencies on `process` or Node APIs —
+ * so it can be safely imported from the web bundle (see web/svelte.config.js alias).
+ *
+ * Runtime parsing lives in ./features.ts. Keep them in sync.
+ */
+export const FEATURE_ENV_VARS = {
+    meetingCapture: 'FEATURE_MEETING_CAPTURE',
+};
+export const DEFAULT_FEATURE_FLAGS = {
+    meetingCapture: true,
+};
+//# sourceMappingURL=feature-flags.js.map

package/dist/core/feature-flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flags.js","sourceRoot":"","sources":["../../src/core/feature-flags.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,cAAc,EAAE,yBAAyB;CACjC,CAAC;AAcX,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IACjD,cAAc,EAAE,IAAI;CACrB,CAAC"}

package/dist/core/features.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Runtime feature flag parsing.
+ *
+ * Env vars are the single source of truth for launch-stage feature gating.
+ * Types/defaults live in ./feature-flags.ts so the web bundle can share them.
+ *
+ * Flags are parsed ONCE at module load and cached. To pick up env changes in tests,
+ * call `refreshFeatureFlags()`.
+ */
+import { DEFAULT_FEATURE_FLAGS, FEATURE_ENV_VARS, type FeatureFlags, type FeatureName } from './feature-flags.js';
+export { DEFAULT_FEATURE_FLAGS, FEATURE_ENV_VARS, type FeatureFlags, type FeatureName };
+export declare function parseFeatureFlag(value: string | undefined, fallback: boolean, envVarName?: string): boolean;
+/** Re-read env vars. Intended for tests; production reads once at startup. */
+export declare function refreshFeatureFlags(env?: NodeJS.ProcessEnv): FeatureFlags;
+export declare function getFeatureFlags(): FeatureFlags;
+export declare function isFeatureEnabled(feature: FeatureName): boolean;

package/dist/core/features.js

@@ -0,0 +1,48 @@
+/**
+ * Runtime feature flag parsing.
+ *
+ * Env vars are the single source of truth for launch-stage feature gating.
+ * Types/defaults live in ./feature-flags.ts so the web bundle can share them.
+ *
+ * Flags are parsed ONCE at module load and cached. To pick up env changes in tests,
+ * call `refreshFeatureFlags()`.
+ */
+import { DEFAULT_FEATURE_FLAGS, FEATURE_ENV_VARS, } from './feature-flags.js';
+export { DEFAULT_FEATURE_FLAGS, FEATURE_ENV_VARS };
+const TRUE_VALUES = new Set(['1', 'true', 'yes', 'on', 'enabled']);
+const FALSE_VALUES = new Set(['0', 'false', 'no', 'off', 'disabled']);
+export function parseFeatureFlag(value, fallback, envVarName) {
+    if (value === undefined)
+        return fallback;
+    const normalized = value.trim().toLowerCase();
+    if (TRUE_VALUES.has(normalized))
+        return true;
+    if (FALSE_VALUES.has(normalized))
+        return false;
+    if (envVarName) {
+        console.warn(`[features] ${envVarName}="${value}" is not a recognized boolean value; using default ${fallback}. ` +
+            `Accepted: ${[...TRUE_VALUES].join('/')} or ${[...FALSE_VALUES].join('/')}.`);
+    }
+    return fallback;
+}
+function computeFeatureFlags(env) {
+    const flags = {};
+    for (const name of Object.keys(FEATURE_ENV_VARS)) {
+        const envVarName = FEATURE_ENV_VARS[name];
+        flags[name] = parseFeatureFlag(env[envVarName], DEFAULT_FEATURE_FLAGS[name], envVarName);
+    }
+    return flags;
+}
+let cachedFlags = computeFeatureFlags(process.env);
+/** Re-read env vars. Intended for tests; production reads once at startup. */
+export function refreshFeatureFlags(env = process.env) {
+    cachedFlags = computeFeatureFlags(env);
+    return cachedFlags;
+}
+export function getFeatureFlags() {
+    return cachedFlags;
+}
+export function isFeatureEnabled(feature) {
+    return cachedFlags[feature];
+}
+//# sourceMappingURL=features.js.map

package/dist/core/features.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.js","sourceRoot":"","sources":["../../src/core/features.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,qBAAqB,EACrB,gBAAgB,GAGjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAuC,CAAC;AAExF,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;AACnE,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC;AAEtE,MAAM,UAAU,gBAAgB,CAAC,KAAyB,EAAE,QAAiB,EAAE,UAAmB;IAChG,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IACzC,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,IAAI,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,IAAI,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/C,IAAI,UAAU,EAAE,CAAC;QACf,OAAO,CAAC,IAAI,CACV,cAAc,UAAU,KAAK,KAAK,sDAAsD,QAAQ,IAAI;YACpG,aAAa,CAAC,GAAG,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAC7E,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,mBAAmB,CAAC,GAAsB;IACjD,MAAM,KAAK,GAAG,EAAkB,CAAC;IACjC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAkB,EAAE,CAAC;QAClE,MAAM,UAAU,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAC1C,KAAK,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,qBAAqB,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC;IAC3F,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,IAAI,WAAW,GAAiB,mBAAmB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;AAEjE,8EAA8E;AAC9E,MAAM,UAAU,mBAAmB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACtE,WAAW,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;IACvC,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,OAAoB;IACnD,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC;AAC9B,CAAC"}

package/dist/core/folder-paths.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Folder path validation and normalization for nested folders within a repo.
+ *
+ * Folder paths are repo-relative POSIX strings (e.g. "clients/acme"). They never
+ * start or end with "/", and segments must be filesystem-safe. Empty string is
+ * the repo root.
+ *
+ * `folder_path` is derived from the file's location on disk at read time — it's
+ * not stored in frontmatter. That keeps the filesystem as the source of truth
+ * and avoids the rename-folder-must-update-N-files problem.
+ */
+export declare class InvalidFolderPathError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate a single folder segment (one level of the path). Throws on:
+ * - empty string
+ * - leading/trailing whitespace or dots
+ * - path separators
+ * - reserved chars or names
+ */
+export declare function validateFolderSegment(name: string): void;
+/**
+ * Normalize a folder path: trim slashes, collapse repeats. Returns "" for root.
+ * Throws on `..` segments (prevents escaping the repo).
+ */
+export declare function normalizeFolderPath(path: string | undefined | null): string;
+/**
+ * Validate a full folder path (one or more segments joined by "/"). Returns
+ * the normalized form for convenience.
+ */
+export declare function validateFolderPath(path: string | undefined | null): string;
+/**
+ * Compute the parent folder path. Returns "" if already at root.
+ */
+export declare function parentFolderPath(path: string): string;
+/**
+ * Derive the folder_path of a file given its absolute path and the repo root.
+ * Returns "" if the file lives at the repo root.
+ */
+export declare function folderPathFromFile(filePath: string, repoPath: string): string;

package/dist/core/folder-paths.js

@@ -0,0 +1,95 @@
+/**
+ * Folder path validation and normalization for nested folders within a repo.
+ *
+ * Folder paths are repo-relative POSIX strings (e.g. "clients/acme"). They never
+ * start or end with "/", and segments must be filesystem-safe. Empty string is
+ * the repo root.
+ *
+ * `folder_path` is derived from the file's location on disk at read time — it's
+ * not stored in frontmatter. That keeps the filesystem as the source of truth
+ * and avoids the rename-folder-must-update-N-files problem.
+ */
+/** Reserved characters disallowed in any folder segment. */
+const RESERVED_CHARS = /[<>:"|?*\\]/;
+/** Names that are not valid folder segments (filesystem-reserved or special). */
+const RESERVED_NAMES = new Set(['.', '..', '.git', '.studiograph', '.gitkeep']);
+export class InvalidFolderPathError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidFolderPathError';
+    }
+}
+/**
+ * Validate a single folder segment (one level of the path). Throws on:
+ * - empty string
+ * - leading/trailing whitespace or dots
+ * - path separators
+ * - reserved chars or names
+ */
+export function validateFolderSegment(name) {
+    if (!name || typeof name !== 'string') {
+        throw new InvalidFolderPathError('Folder segment must be a non-empty string');
+    }
+    if (name !== name.trim()) {
+        throw new InvalidFolderPathError(`Folder segment cannot have leading or trailing whitespace: "${name}"`);
+    }
+    if (name.startsWith('.') || name.endsWith('.')) {
+        throw new InvalidFolderPathError(`Folder segment cannot start or end with "." : "${name}"`);
+    }
+    if (name.includes('/')) {
+        throw new InvalidFolderPathError(`Folder segment cannot contain "/" : "${name}"`);
+    }
+    if (RESERVED_CHARS.test(name)) {
+        throw new InvalidFolderPathError(`Folder segment contains reserved characters: "${name}"`);
+    }
+    if (RESERVED_NAMES.has(name)) {
+        throw new InvalidFolderPathError(`Folder segment uses a reserved name: "${name}"`);
+    }
+}
+/**
+ * Normalize a folder path: trim slashes, collapse repeats. Returns "" for root.
+ * Throws on `..` segments (prevents escaping the repo).
+ */
+export function normalizeFolderPath(path) {
+    if (!path)
+        return '';
+    // Strip leading/trailing slashes, split, drop empties, validate each.
+    const segments = path
+        .replace(/^\/+|\/+$/g, '')
+        .split('/')
+        .filter(s => s.length > 0);
+    for (const segment of segments) {
+        validateFolderSegment(segment);
+    }
+    return segments.join('/');
+}
+/**
+ * Validate a full folder path (one or more segments joined by "/"). Returns
+ * the normalized form for convenience.
+ */
+export function validateFolderPath(path) {
+    return normalizeFolderPath(path);
+}
+/**
+ * Compute the parent folder path. Returns "" if already at root.
+ */
+export function parentFolderPath(path) {
+    const normalized = normalizeFolderPath(path);
+    if (!normalized)
+        return '';
+    const idx = normalized.lastIndexOf('/');
+    return idx === -1 ? '' : normalized.slice(0, idx);
+}
+/**
+ * Derive the folder_path of a file given its absolute path and the repo root.
+ * Returns "" if the file lives at the repo root.
+ */
+export function folderPathFromFile(filePath, repoPath) {
+    const normalizedRepo = repoPath.replace(/\/+$/, '');
+    if (!filePath.startsWith(normalizedRepo + '/'))
+        return '';
+    const rel = filePath.slice(normalizedRepo.length + 1);
+    const idx = rel.lastIndexOf('/');
+    return idx === -1 ? '' : rel.slice(0, idx);
+}
+//# sourceMappingURL=folder-paths.js.map

package/dist/core/folder-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder-paths.js","sourceRoot":"","sources":["../../src/core/folder-paths.ts"],"names":[],"mappings":"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"}

package/dist/core/folder-sidecar.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Per-folder sidecar carrying optional display_name override. Lives inside
+ * the folder itself so it travels atomically with FS rename / move / cross-repo
+ * transfer — the same way an entity .md file's frontmatter travels with the
+ * file.
+ */
+export declare const FOLDER_SIDECAR = ".studiograph-folder.json";
+export declare function folderSidecarPath(absDir: string): string;
+/**
+ * Read the display_name override from a folder's sidecar. Returns null when
+ * the sidecar is absent, unreadable, or malformed; callers fall back to the
+ * slug-derived display name.
+ */
+export declare function readFolderSidecar(absDir: string): string | null;
+export declare function writeFolderSidecar(absDir: string, displayName: string): string;
+export declare function removeFolderSidecar(absDir: string): string | null;

package/dist/core/folder-sidecar.js

@@ -0,0 +1,45 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+/**
+ * Per-folder sidecar carrying optional display_name override. Lives inside
+ * the folder itself so it travels atomically with FS rename / move / cross-repo
+ * transfer — the same way an entity .md file's frontmatter travels with the
+ * file.
+ */
+export const FOLDER_SIDECAR = '.studiograph-folder.json';
+export function folderSidecarPath(absDir) {
+    return join(absDir, FOLDER_SIDECAR);
+}
+/**
+ * Read the display_name override from a folder's sidecar. Returns null when
+ * the sidecar is absent, unreadable, or malformed; callers fall back to the
+ * slug-derived display name.
+ */
+export function readFolderSidecar(absDir) {
+    const sidecarPath = folderSidecarPath(absDir);
+    if (!existsSync(sidecarPath))
+        return null;
+    try {
+        const raw = readFileSync(sidecarPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        const display = parsed?.display_name;
+        return typeof display === 'string' && display.trim() ? display.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeFolderSidecar(absDir, displayName) {
+    mkdirSync(absDir, { recursive: true });
+    const sidecarPath = folderSidecarPath(absDir);
+    writeFileSync(sidecarPath, JSON.stringify({ display_name: displayName }, null, 2) + '\n', 'utf-8');
+    return sidecarPath;
+}
+export function removeFolderSidecar(absDir) {
+    const sidecarPath = folderSidecarPath(absDir);
+    if (!existsSync(sidecarPath))
+        return null;
+    rmSync(sidecarPath, { force: true });
+    return sidecarPath;
+}
+//# sourceMappingURL=folder-sidecar.js.map

package/dist/core/folder-sidecar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder-sidecar.js","sourceRoot":"","sources":["../../src/core/folder-sidecar.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AAChF,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,0BAA0B,CAAC;AAEzD,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,OAAO,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,MAAM,WAAW,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC9C,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,MAAM,OAAO,GAAG,MAAM,EAAE,YAAY,CAAC;QACrC,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,MAAc,EAAE,WAAmB;IACpE,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,MAAM,WAAW,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC9C,aAAa,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,YAAY,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;IACnG,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,MAAM,WAAW,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC9C,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,MAAM,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACrC,OAAO,WAAW,CAAC;AACrB,CAAC"}