@fractary/core 0.3.2 → 0.4.0

package/dist/config/loader.js

@@ -0,0 +1,277 @@
+"use strict";
+/**
+ * @fractary/core - Unified Configuration Loader
+ *
+ * Builds on yaml-config.ts to provide a unified configuration object
+ * with integrated authentication support.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadEnv = loadEnv;
+exports.isEnvLoaded = isEnvLoaded;
+exports.loadConfig = loadConfig;
+exports.loadConfigSync = loadConfigSync;
+const dotenv = __importStar(require("dotenv"));
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const yaml_config_1 = require("../common/yaml-config");
+const auth_1 = require("../auth");
+const yaml_config_2 = require("../common/yaml-config");
+/** Track whether loadEnv has been called */
+let envLoaded = false;
+/**
+ * Load environment variables from .env files
+ *
+ * This function explicitly loads .env files - it must be called manually
+ * rather than being a side effect of importing the module.
+ *
+ * Searches for .env files in the following order:
+ * 1. Current working directory
+ * 2. Project root (directory containing .fractary or .git)
+ *
+ * @param options Loading options
+ * @returns true if .env was loaded, false if no .env file found
+ *
+ * @example
+ * ```typescript
+ * import { loadEnv, loadConfig } from '@fractary/core';
+ *
+ * // Explicitly load .env before loading config
+ * loadEnv();
+ * const config = await loadConfig();
+ * ```
+ */
+function loadEnv(options = {}) {
+    const { cwd = process.cwd(), force = false } = options;
+    // Skip if already loaded (unless force is true)
+    if (envLoaded && !force) {
+        return true;
+    }
+    // Try loading from current working directory first
+    const cwdEnvPath = path.join(cwd, '.env');
+    if (fs.existsSync(cwdEnvPath)) {
+        dotenv.config({ path: cwdEnvPath });
+        envLoaded = true;
+        return true;
+    }
+    // Try loading from project root
+    try {
+        const projectRoot = (0, yaml_config_2.findProjectRoot)(cwd);
+        const rootEnvPath = path.join(projectRoot, '.env');
+        if (fs.existsSync(rootEnvPath)) {
+            dotenv.config({ path: rootEnvPath });
+            envLoaded = true;
+            return true;
+        }
+    }
+    catch {
+        // findProjectRoot failed - that's okay
+    }
+    return false;
+}
+/**
+ * Check if environment variables have been loaded
+ *
+ * @returns true if loadEnv() has been called successfully
+ */
+function isEnvLoaded() {
+    return envLoaded;
+}
+/**
+ * Extract GitHub configuration from yaml config
+ *
+ * Looks for GitHub configuration in:
+ * 1. work.handlers.github
+ * 2. repo.handlers.github
+ *
+ * @param config Raw yaml configuration
+ * @returns Extracted GitHub configuration or undefined
+ */
+function extractGitHubConfig(config) {
+    // Try work handlers first
+    const workGithub = config.work?.handlers?.github;
+    const repoGithub = config.repo?.handlers?.github;
+    // Merge configurations (work takes priority for auth, repo for project info)
+    const github = {};
+    let hasConfig = false;
+    // Extract token
+    if (workGithub?.token) {
+        github.token = workGithub.token;
+        hasConfig = true;
+    }
+    else if (repoGithub?.token) {
+        github.token = repoGithub.token;
+        hasConfig = true;
+    }
+    // Extract organization
+    if (workGithub?.organization) {
+        github.organization = workGithub.organization;
+        hasConfig = true;
+    }
+    else if (repoGithub?.organization) {
+        github.organization = repoGithub.organization;
+        hasConfig = true;
+    }
+    // Extract project (owner/repo)
+    if (workGithub?.project) {
+        github.project = workGithub.project;
+        hasConfig = true;
+    }
+    else if (repoGithub?.project) {
+        github.project = repoGithub.project;
+        hasConfig = true;
+    }
+    else if (workGithub?.owner && workGithub?.repo) {
+        github.project = `${workGithub.owner}/${workGithub.repo}`;
+        hasConfig = true;
+    }
+    else if (repoGithub?.owner && repoGithub?.repo) {
+        github.project = `${repoGithub.owner}/${repoGithub.repo}`;
+        hasConfig = true;
+    }
+    // Extract GitHub App config
+    const appConfig = workGithub?.app || repoGithub?.app;
+    if (appConfig?.id && appConfig?.installation_id) {
+        github.app = {
+            id: String(appConfig.id),
+            installation_id: String(appConfig.installation_id),
+            private_key_path: appConfig.private_key_path,
+            private_key_env_var: appConfig.private_key_env_var,
+        };
+        hasConfig = true;
+    }
+    return hasConfig ? github : undefined;
+}
+/**
+ * Load unified configuration with authentication
+ *
+ * This function:
+ * 1. Loads and parses the YAML configuration
+ * 2. Extracts GitHub configuration from handlers
+ * 3. Creates a TokenProvider for authentication (if configured)
+ * 4. Returns a unified config object
+ *
+ * Note: dotenv should be imported at the entry point, so environment
+ * variables are already loaded when this function is called.
+ *
+ * @param options Configuration loading options
+ * @returns Loaded configuration with authentication
+ *
+ * @example
+ * ```typescript
+ * const config = await loadConfig();
+ *
+ * if (config.tokenProvider) {
+ *   const token = await config.tokenProvider.getToken();
+ *   // Use token for API calls
+ * }
+ * ```
+ */
+async function loadConfig(options = {}) {
+    const { skipAuth = false, ...yamlOptions } = options;
+    // Load raw YAML configuration
+    const raw = (0, yaml_config_1.loadYamlConfig)(yamlOptions);
+    // Handle case where config file doesn't exist
+    if (!raw) {
+        return {
+            version: '0.0.0',
+            raw: { version: '0.0.0' },
+        };
+    }
+    // Extract GitHub configuration
+    const github = extractGitHubConfig(raw);
+    // Create token provider (unless skipped)
+    let tokenProvider;
+    if (!skipAuth && github) {
+        try {
+            const githubConfig = {
+                token: github.token,
+                organization: github.organization,
+                project: github.project,
+                app: github.app,
+            };
+            tokenProvider = (0, auth_1.createTokenProvider)(githubConfig);
+        }
+        catch {
+            // Token provider creation failed - that's okay, it's optional
+            // The user might not have configured authentication yet
+        }
+    }
+    return {
+        version: raw.version || '0.0.0',
+        github,
+        tokenProvider,
+        work: raw.work,
+        repo: raw.repo,
+        logs: raw.logs,
+        file: raw.file,
+        spec: raw.spec,
+        docs: raw.docs,
+        codex: raw.codex,
+        raw,
+    };
+}
+/**
+ * Load configuration synchronously (without token provider)
+ *
+ * Useful for cases where you only need the configuration data
+ * without authentication.
+ *
+ * @param options Configuration loading options
+ * @returns Loaded configuration without token provider
+ */
+function loadConfigSync(options = {}) {
+    const raw = (0, yaml_config_1.loadYamlConfig)(options);
+    if (!raw) {
+        return {
+            version: '0.0.0',
+            raw: { version: '0.0.0' },
+        };
+    }
+    const github = extractGitHubConfig(raw);
+    return {
+        version: raw.version || '0.0.0',
+        github,
+        work: raw.work,
+        repo: raw.repo,
+        logs: raw.logs,
+        file: raw.file,
+        spec: raw.spec,
+        docs: raw.docs,
+        codex: raw.codex,
+        raw,
+    };
+}
+//# sourceMappingURL=loader.js.map

package/dist/config/loader.js.map

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

package/dist/docs/index.d.ts

@@ -2,7 +2,12 @@
  * @fractary/core - Docs Module
  *
  * Documentation management and organization.
+ *
+ * Doc types are now stored as YAML/Markdown files in the doc-types/ directory
+ * at the repository root. Use DocTypeRegistry to load and access them.
  */
 export { DocsManager } from './manager';
+export { DocTypeRegistry } from './type-registry';
+export type { CustomDocTypeConfig, DocTypeRegistryConfig } from './type-registry';
 export * from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/docs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/docs/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/docs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,YAAY,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAClF,cAAc,SAAS,CAAC"}

package/dist/docs/index.js

@@ -3,6 +3,9 @@
  * @fractary/core - Docs Module
  *
  * Documentation management and organization.
+ *
+ * Doc types are now stored as YAML/Markdown files in the doc-types/ directory
+ * at the repository root. Use DocTypeRegistry to load and access them.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -19,8 +22,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DocsManager = void 0;
+exports.DocTypeRegistry = exports.DocsManager = void 0;
 var manager_1 = require("./manager");
 Object.defineProperty(exports, "DocsManager", { enumerable: true, get: function () { return manager_1.DocsManager; } });
+var type_registry_1 = require("./type-registry");
+Object.defineProperty(exports, "DocTypeRegistry", { enumerable: true, get: function () { return type_registry_1.DocTypeRegistry; } });
 __exportStar(require("./types"), exports);
 //# sourceMappingURL=index.js.map

package/dist/docs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/docs/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;;;;;;;;;;;;;;;AAEH,qCAAwC;AAA/B,sGAAA,WAAW,OAAA;AACpB,0CAAwB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/docs/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;;;;;;;;;;;;;;;AAEH,qCAAwC;AAA/B,sGAAA,WAAW,OAAA;AACpB,iDAAkD;AAAzC,gHAAA,eAAe,OAAA;AAExB,0CAAwB"}

package/dist/docs/manager.d.ts

@@ -10,25 +10,52 @@ import { Doc, DocFormat, DocMetadata, DocSearchQuery, DocsManagerConfig } from '
 export declare class DocsManager {
     private docsDir;
     private defaultFormat;
+    private metadataMode;
     constructor(config: DocsManagerConfig);
     private ensureDir;
     private getDocPath;
     private getMetadataPath;
     private getFileExtension;
+    /**
+     * Determine the effective metadata mode for a document format
+     * Frontmatter only makes sense for markdown files
+     */
+    private getEffectiveMetadataMode;
+    /**
+     * Parse frontmatter from markdown content
+     */
+    private parseFrontmatter;
+    /**
+     * Write frontmatter to markdown content
+     */
+    private writeFrontmatter;
+    /**
+     * Extract body content from content that may have frontmatter
+     */
+    private extractBody;
     /**
      * Create a new document
+     * @param id - Document identifier
+     * @param content - Document body content (without frontmatter)
+     * @param metadata - Document metadata
+     * @param format - Document format (default: markdown)
      */
     createDoc(id: string, content: string, metadata: DocMetadata, format?: DocFormat): Promise<Doc>;
     /**
      * Get a document by ID
+     * Supports both frontmatter and sidecar metadata modes
      */
     getDoc(id: string): Promise<Doc | null>;
     /**
      * Update a document
+     * @param id - Document identifier
+     * @param content - New body content (without frontmatter)
+     * @param metadata - Metadata fields to update (merged with existing)
      */
     updateDoc(id: string, content: string, metadata?: Partial<DocMetadata>): Promise<Doc | null>;
     /**
      * Delete a document
+     * Removes both the document file and any sidecar metadata file if it exists
      */
     deleteDoc(id: string): Promise<boolean>;
     /**

package/dist/docs/manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/docs/manager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EACL,GAAG,EACH,SAAS,EACT,WAAW,EACX,cAAc,EACd,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,aAAa,CAAY;gBAErB,MAAM,EAAE,iBAAiB;IAMrC,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,gBAAgB;IAUxB;;OAEG;IACG,SAAS,CACb,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,WAAW,EACrB,MAAM,CAAC,EAAE,SAAS,GACjB,OAAO,CAAC,GAAG,CAAC;IA2Bf;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IA6B7C;;OAEG;IACG,SAAS,CACb,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC9B,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IA2BtB;;OAEG;IACG,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAoB7C;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IA4BhC;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAsDvD;;OAEG;IACG,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAI9C"}
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/docs/manager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EACL,GAAG,EACH,SAAS,EACT,WAAW,EACX,cAAc,EACd,iBAAiB,EAElB,MAAM,SAAS,CAAC;AAUjB;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,aAAa,CAAY;IACjC,OAAO,CAAC,YAAY,CAAe;gBAEvB,MAAM,EAAE,iBAAiB;IAOrC,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,gBAAgB;IAUxB;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAOhC;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAiDxB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAuCxB;;OAEG;IACH,OAAO,CAAC,WAAW;IAKnB;;;;;;OAMG;IACG,SAAS,CACb,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,WAAW,EACrB,MAAM,CAAC,EAAE,SAAS,GACjB,OAAO,CAAC,GAAG,CAAC;IAmCf;;;OAGG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAwC7C;;;;;OAKG;IACG,SAAS,CACb,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC9B,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAsCtB;;;OAGG;IACG,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAqB7C;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IA4BhC;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IA2DvD;;OAEG;IACG,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAI9C"}

package/dist/docs/manager.js

@@ -48,9 +48,11 @@ const yaml = __importStar(require("js-yaml"));
 class DocsManager {
     docsDir;
     defaultFormat;
+    metadataMode;
     constructor(config) {
         this.docsDir = config.docsDir;
         this.defaultFormat = config.defaultFormat || 'markdown';
+        this.metadataMode = config.metadataMode || 'frontmatter';
         this.ensureDir(this.docsDir);
     }
     ensureDir(dirPath) {
@@ -74,26 +76,144 @@ class DocsManager {
         };
         return extensions[format];
     }
+    /**
+     * Determine the effective metadata mode for a document format
+     * Frontmatter only makes sense for markdown files
+     */
+    getEffectiveMetadataMode(format) {
+        if (format !== 'markdown') {
+            return 'sidecar';
+        }
+        return this.metadataMode;
+    }
+    /**
+     * Parse frontmatter from markdown content
+     */
+    parseFrontmatter(content) {
+        const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
+        const match = content.match(frontmatterRegex);
+        if (!match) {
+            // No frontmatter found, return content as-is with minimal metadata
+            return {
+                metadata: { title: '' },
+                body: content,
+            };
+        }
+        const frontmatterContent = match[1];
+        const body = match[2];
+        let metadata;
+        try {
+            const parsed = yaml.load(frontmatterContent);
+            metadata = {
+                title: parsed.title || '',
+                description: parsed.description,
+                authors: parsed.authors,
+                tags: parsed.tags,
+                docType: parsed.docType,
+                status: parsed.status,
+                version: parsed.version,
+            };
+            // Parse dates
+            if (parsed.createdAt) {
+                metadata.createdAt = new Date(parsed.createdAt);
+            }
+            if (parsed.updatedAt) {
+                metadata.updatedAt = new Date(parsed.updatedAt);
+            }
+            // Copy any additional fields
+            for (const [key, value] of Object.entries(parsed)) {
+                if (!(key in metadata)) {
+                    metadata[key] = value;
+                }
+            }
+        }
+        catch {
+            metadata = { title: '' };
+        }
+        return { metadata, body };
+    }
+    /**
+     * Write frontmatter to markdown content
+     */
+    writeFrontmatter(metadata, body) {
+        // Prepare metadata object for YAML serialization
+        const yamlMetadata = {};
+        // Add standard fields
+        if (metadata.title)
+            yamlMetadata.title = metadata.title;
+        if (metadata.description)
+            yamlMetadata.description = metadata.description;
+        if (metadata.authors && metadata.authors.length > 0)
+            yamlMetadata.authors = metadata.authors;
+        if (metadata.tags && metadata.tags.length > 0)
+            yamlMetadata.tags = metadata.tags;
+        if (metadata.docType)
+            yamlMetadata.docType = metadata.docType;
+        if (metadata.status)
+            yamlMetadata.status = metadata.status;
+        if (metadata.version)
+            yamlMetadata.version = metadata.version;
+        // Add dates
+        if (metadata.createdAt) {
+            yamlMetadata.createdAt = metadata.createdAt instanceof Date
+                ? metadata.createdAt.toISOString()
+                : metadata.createdAt;
+        }
+        if (metadata.updatedAt) {
+            yamlMetadata.updatedAt = metadata.updatedAt instanceof Date
+                ? metadata.updatedAt.toISOString()
+                : metadata.updatedAt;
+        }
+        // Add any additional custom fields
+        for (const [key, value] of Object.entries(metadata)) {
+            if (value !== undefined &&
+                !['title', 'description', 'authors', 'tags', 'docType', 'status', 'version', 'createdAt', 'updatedAt'].includes(key)) {
+                yamlMetadata[key] = value;
+            }
+        }
+        const frontmatter = yaml.dump(yamlMetadata, { lineWidth: -1 });
+        return `---\n${frontmatter}---\n\n${body}`;
+    }
+    /**
+     * Extract body content from content that may have frontmatter
+     */
+    extractBody(content) {
+        const result = this.parseFrontmatter(content);
+        return result.body;
+    }
     /**
      * Create a new document
+     * @param id - Document identifier
+     * @param content - Document body content (without frontmatter)
+     * @param metadata - Document metadata
+     * @param format - Document format (default: markdown)
      */
     async createDoc(id, content, metadata, format) {
         const docFormat = format || this.defaultFormat;
         const docPath = this.getDocPath(id, docFormat);
-        const metaPath = this.getMetadataPath(id);
+        const effectiveMode = this.getEffectiveMetadataMode(docFormat);
         // Add timestamps
         const fullMetadata = {
             ...metadata,
             createdAt: metadata.createdAt || new Date(),
             updatedAt: new Date(),
         };
-        // Write content
-        fs.writeFileSync(docPath, content, 'utf-8');
-        // Write metadata
-        fs.writeFileSync(metaPath, yaml.dump(fullMetadata), 'utf-8');
+        // Extract body content in case content already has frontmatter
+        const bodyContent = this.extractBody(content);
+        if (effectiveMode === 'frontmatter') {
+            // Write content with embedded frontmatter
+            const fullContent = this.writeFrontmatter(fullMetadata, bodyContent);
+            fs.writeFileSync(docPath, fullContent, 'utf-8');
+        }
+        else {
+            // Sidecar mode: separate content and metadata files
+            const metaPath = this.getMetadataPath(id);
+            fs.writeFileSync(docPath, bodyContent, 'utf-8');
+            fs.writeFileSync(metaPath, yaml.dump(fullMetadata), 'utf-8');
+        }
         return {
             id,
-            content,
+            content: bodyContent,
             format: docFormat,
             metadata: fullMetadata,
             path: docPath,
@@ -101,6 +221,7 @@ class DocsManager {
     }
     /**
      * Get a document by ID
+     * Supports both frontmatter and sidecar metadata modes
      */
     async getDoc(id) {
         // Try to find the doc with any format
@@ -108,12 +229,24 @@ class DocsManager {
         for (const format of formats) {
             const docPath = this.getDocPath(id, format);
             if (fs.existsSync(docPath)) {
-                const content = fs.readFileSync(docPath, 'utf-8');
-                const metaPath = this.getMetadataPath(id);
+                const rawContent = fs.readFileSync(docPath, 'utf-8');
+                const effectiveMode = this.getEffectiveMetadataMode(format);
                 let metadata = { title: id };
-                if (fs.existsSync(metaPath)) {
-                    const metaContent = fs.readFileSync(metaPath, 'utf-8');
-                    metadata = yaml.load(metaContent);
+                let content;
+                if (effectiveMode === 'frontmatter') {
+                    // Parse frontmatter from content
+                    const result = this.parseFrontmatter(rawContent);
+                    metadata = result.metadata.title ? result.metadata : { ...metadata, ...result.metadata };
+                    content = result.body;
+                }
+                else {
+                    // Sidecar mode: check for .meta.yaml file
+                    content = rawContent;
+                    const metaPath = this.getMetadataPath(id);
+                    if (fs.existsSync(metaPath)) {
+                        const metaContent = fs.readFileSync(metaPath, 'utf-8');
+                        metadata = yaml.load(metaContent);
+                    }
                 }
                 return {
                     id,
@@ -128,6 +261,9 @@ class DocsManager {
     }
     /**
      * Update a document
+     * @param id - Document identifier
+     * @param content - New body content (without frontmatter)
+     * @param metadata - Metadata fields to update (merged with existing)
      */
     async updateDoc(id, content, metadata) {
         const existingDoc = await this.getDoc(id);
@@ -140,12 +276,23 @@ class DocsManager {
             updatedAt: new Date(),
         };
         const docPath = this.getDocPath(id, existingDoc.format);
-        const metaPath = this.getMetadataPath(id);
-        fs.writeFileSync(docPath, content, 'utf-8');
-        fs.writeFileSync(metaPath, yaml.dump(updatedMetadata), 'utf-8');
+        const effectiveMode = this.getEffectiveMetadataMode(existingDoc.format);
+        // Extract body content in case content already has frontmatter
+        const bodyContent = this.extractBody(content);
+        if (effectiveMode === 'frontmatter') {
+            // Write content with embedded frontmatter
+            const fullContent = this.writeFrontmatter(updatedMetadata, bodyContent);
+            fs.writeFileSync(docPath, fullContent, 'utf-8');
+        }
+        else {
+            // Sidecar mode: separate content and metadata files
+            const metaPath = this.getMetadataPath(id);
+            fs.writeFileSync(docPath, bodyContent, 'utf-8');
+            fs.writeFileSync(metaPath, yaml.dump(updatedMetadata), 'utf-8');
+        }
         return {
             id,
-            content,
+            content: bodyContent,
             format: existingDoc.format,
             metadata: updatedMetadata,
             path: docPath,
@@ -153,6 +300,7 @@ class DocsManager {
     }
     /**
      * Delete a document
+     * Removes both the document file and any sidecar metadata file if it exists
      */
     async deleteDoc(id) {
         const doc = await this.getDoc(id);
@@ -164,6 +312,7 @@ class DocsManager {
         if (fs.existsSync(docPath)) {
             fs.unlinkSync(docPath);
         }
+        // Also delete sidecar metadata file if it exists (for backward compatibility)
         if (fs.existsSync(metaPath)) {
             fs.unlinkSync(metaPath);
         }
@@ -216,6 +365,10 @@ class DocsManager {
         if (query.author) {
             results = results.filter((doc) => doc.metadata.authors?.includes(query.author));
         }
+        // Filter by docType
+        if (query.docType) {
+            results = results.filter((doc) => doc.metadata.docType === query.docType);
+        }
         // Filter by date range
         if (query.dateRange) {
             results = results.filter((doc) => {