@yourtechtribe-labs/koncept-core 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Albert Gil López — yourtechtribe-labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# @yourtechtribe-labs/koncept-core
+
+> Core schema, parser, and indexer for [koncepto](https://github.com/yourtechtribe-labs/koncept-mcp) — semantic concept graphs for codebases.
+
+**Status**: pre-alpha (`v0.1.0-alpha.1`).
+
+## What this package contains
+
+- **Zod schema** for the YAML concept format (`ConceptSchema`, `KEBAB_ID_REGEX`, enums)
+- **Parser** that loads `.koncept/concepts/*.yaml` and validates against the schema
+- **Indexer** that scans the registry, detects duplicate ids, unresolved cross-refs, and missing participant files
+- **Search API** for in-memory queries over the index
+- **Path helpers** for cross-platform path normalization
+
+This is the runtime foundation. End users normally interact with [`@yourtechtribe-labs/koncept-cli`](https://www.npmjs.com/package/@yourtechtribe-labs/koncept-cli) or [`@yourtechtribe-labs/koncept-mcp-server`](https://www.npmjs.com/package/@yourtechtribe-labs/koncept-mcp-server) and don't import this directly.
+
+## Install
+
+```bash
+pnpm add @yourtechtribe-labs/koncept-core@alpha
+```
+
+## Usage
+
+```ts
+import { indexConcepts, isIndexClean, ConceptSchema } from '@yourtechtribe-labs/koncept-core'
+
+const result = await indexConcepts(process.cwd())
+if (!isIndexClean(result)) {
+  console.error('registry has issues:', result)
+}
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## Repository
+
+Source, issues, and full docs at [github.com/yourtechtribe-labs/koncept-mcp](https://github.com/yourtechtribe-labs/koncept-mcp).

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export declare const VERSION = "0.1.0-alpha.0";
+export { ConceptSchema, IndexEntrySchema, RoleEnum, ConceptTypeEnum, SeverityEnum, StatusEnum, } from './schema.js';
+export type { Concept, IndexEntry, Participant, Invariant, SourceOfTruth, Role, ConceptType, Severity, Status, } from './schema.js';
+export { parseConceptString, parseConceptFile } from './parser.js';
+export type { ParseResult, ParseError, ParseErrorType } from './parser.js';
+export { indexConcepts, writeIndex, isIndexClean } from './indexer.js';
+export type { IndexResult, IndexErrorEntry, DuplicateId, UnresolvedRelated, MissingFile, } from './indexer.js';
+export { searchEntries } from './search.js';
+export type { SearchHit, MatchField } from './search.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,OAAO,kBAAkB,CAAA;AAItC,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,UAAU,GACX,MAAM,aAAa,CAAA;AACpB,YAAY,EACV,OAAO,EACP,UAAU,EACV,WAAW,EACX,SAAS,EACT,aAAa,EACb,IAAI,EACJ,WAAW,EACX,QAAQ,EACR,MAAM,GACP,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAClE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAG1E,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AACtE,YAAY,EACV,WAAW,EACX,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,WAAW,GACZ,MAAM,cAAc,CAAA;AAGrB,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,14 @@
+// @yourtechtribe-labs/koncept-core — public API.
+// Greenfield: keep the surface intentional. Internal helpers (regexes,
+// constants, sub-schemas) stay un-exported.
+export const VERSION = '0.1.0-alpha.0';
+// Schema — top-level types + main schemas. Sub-schemas (Participant, Invariant,
+// SourceOfTruth) and the kebab-id regex stay internal.
+export { ConceptSchema, IndexEntrySchema, RoleEnum, ConceptTypeEnum, SeverityEnum, StatusEnum, } from './schema.js';
+// Parser
+export { parseConceptString, parseConceptFile } from './parser.js';
+// Indexer
+export { indexConcepts, writeIndex, isIndexClean } from './indexer.js';
+// Search
+export { searchEntries } from './search.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,uEAAuE;AACvE,4CAA4C;AAE5C,MAAM,CAAC,MAAM,OAAO,GAAG,eAAe,CAAA;AAEtC,gFAAgF;AAChF,uDAAuD;AACvD,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,UAAU,GACX,MAAM,aAAa,CAAA;AAapB,SAAS;AACT,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAGlE,UAAU;AACV,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAStE,SAAS;AACT,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA"}

package/dist/indexer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Indexer — scan `.koncept/concepts/*.yaml`, parse them, validate cross-refs,
+ * and produce a denormalized IndexEntry list.
+ *
+ * Validations performed:
+ *  - YAML/Zod parse errors (collected per-file).
+ *  - Duplicate concept ids across files.
+ *  - related_concepts pointing to ids that don't exist.
+ *  - participants[].file paths that don't resolve on disk.
+ */
+import { type ParseError } from './parser.js';
+import type { IndexEntry } from './schema.js';
+export interface DuplicateId {
+    id: string;
+    files: string[];
+}
+export interface UnresolvedRelated {
+    conceptId: string;
+    missingRelatedId: string;
+}
+export interface MissingFile {
+    conceptId: string;
+    missingFile: string;
+}
+export interface IndexErrorEntry {
+    filePath: string;
+    errors: ParseError[];
+}
+export interface IndexResult {
+    entries: IndexEntry[];
+    errors: IndexErrorEntry[];
+    duplicateIds: DuplicateId[];
+    unresolvedRelated: UnresolvedRelated[];
+    missingFiles: MissingFile[];
+}
+/**
+ * Scan a project root and produce the full index report.
+ * @param rootDir absolute or relative path to the project root containing `.koncept/`
+ */
+export declare function indexConcepts(rootDir: string): Promise<IndexResult>;
+/**
+ * Persist the index to `.koncept/index.json` (gitignored cache).
+ */
+export declare function writeIndex(rootDir: string, entries: IndexEntry[]): Promise<void>;
+/**
+ * True if the IndexResult is fully clean (no errors of any kind).
+ */
+export declare function isIndexClean(result: IndexResult): boolean;
+//# sourceMappingURL=indexer.d.ts.map

package/dist/indexer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexer.d.ts","sourceRoot":"","sources":["../src/indexer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAE/D,OAAO,KAAK,EAAW,UAAU,EAAE,MAAM,aAAa,CAAA;AAEtD,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,UAAU,EAAE,CAAA;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,UAAU,EAAE,CAAA;IACrB,MAAM,EAAE,eAAe,EAAE,CAAA;IACzB,YAAY,EAAE,WAAW,EAAE,CAAA;IAC3B,iBAAiB,EAAE,iBAAiB,EAAE,CAAA;IACtC,YAAY,EAAE,WAAW,EAAE,CAAA;CAC5B;AAKD;;;GAGG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAoFzE;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAGtF;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAOzD"}

package/dist/indexer.js

@@ -0,0 +1,114 @@
+/**
+ * Indexer — scan `.koncept/concepts/*.yaml`, parse them, validate cross-refs,
+ * and produce a denormalized IndexEntry list.
+ *
+ * Validations performed:
+ *  - YAML/Zod parse errors (collected per-file).
+ *  - Duplicate concept ids across files.
+ *  - related_concepts pointing to ids that don't exist.
+ *  - participants[].file paths that don't resolve on disk.
+ */
+import { glob } from 'glob';
+import { stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseConceptFile } from './parser.js';
+import { resolveRelative, normalizeForward } from './paths.js';
+const CONCEPTS_GLOB = '.koncept/concepts/*.yaml';
+const INDEX_FILENAME = '.koncept/index.json';
+/**
+ * Scan a project root and produce the full index report.
+ * @param rootDir absolute or relative path to the project root containing `.koncept/`
+ */
+export async function indexConcepts(rootDir) {
+    // Pass cwd explicitly + posix:true so glob handles forward slashes natively
+    // and avoids meta-character escaping issues if rootDir contains `[`, `(`, `*`.
+    const files = await glob(CONCEPTS_GLOB, {
+        cwd: rootDir,
+        absolute: true,
+        nodir: true,
+        posix: true,
+    });
+    const result = {
+        entries: [],
+        errors: [],
+        duplicateIds: [],
+        unresolvedRelated: [],
+        missingFiles: [],
+    };
+    // Per-file parse + collect concepts (parallel; preserves ordering by source array).
+    const parsedAll = await Promise.all(files.map((filePath) => parseConceptFile(filePath)));
+    const concepts = [];
+    for (const parsed of parsedAll) {
+        if (parsed.concept === null) {
+            result.errors.push({ filePath: parsed.filePath, errors: parsed.errors });
+            continue;
+        }
+        concepts.push({ concept: parsed.concept, filePath: parsed.filePath });
+    }
+    const idToFiles = new Map();
+    for (const { concept, filePath } of concepts) {
+        const list = idToFiles.get(concept.id) ?? [];
+        list.push(filePath);
+        idToFiles.set(concept.id, list);
+    }
+    for (const [id, fileList] of idToFiles) {
+        if (fileList.length > 1) {
+            result.duplicateIds.push({ id, files: fileList });
+        }
+    }
+    // Duplicate ids stay in `knownIds` so related_concepts pointing at them still
+    // resolve (the duplicate is reported separately via `duplicateIds`).
+    const knownIds = new Set(idToFiles.keys());
+    await Promise.all(concepts.map(async ({ concept, filePath }) => {
+        for (const relatedId of concept.related_concepts) {
+            if (!knownIds.has(relatedId)) {
+                result.unresolvedRelated.push({
+                    conceptId: concept.id,
+                    missingRelatedId: relatedId,
+                });
+            }
+        }
+        const participantChecks = await Promise.all(concept.participants.map(async (participant) => {
+            const abs = resolveRelative(rootDir, participant.file);
+            try {
+                await stat(abs);
+                return null;
+            }
+            catch {
+                return participant.file;
+            }
+        }));
+        for (const missing of participantChecks) {
+            if (missing !== null) {
+                result.missingFiles.push({ conceptId: concept.id, missingFile: missing });
+            }
+        }
+        result.entries.push({
+            id: concept.id,
+            name: concept.name,
+            type: concept.type,
+            status: concept.status,
+            participants_paths: concept.participants.map((p) => normalizeForward(p.file)),
+            tags: concept.tags,
+            file: normalizeForward(filePath),
+        });
+    }));
+    return result;
+}
+/**
+ * Persist the index to `.koncept/index.json` (gitignored cache).
+ */
+export async function writeIndex(rootDir, entries) {
+    const path = join(rootDir, INDEX_FILENAME);
+    await writeFile(path, JSON.stringify(entries, null, 2) + '\n', 'utf-8');
+}
+/**
+ * True if the IndexResult is fully clean (no errors of any kind).
+ */
+export function isIndexClean(result) {
+    return (result.errors.length === 0 &&
+        result.duplicateIds.length === 0 &&
+        result.unresolvedRelated.length === 0 &&
+        result.missingFiles.length === 0);
+}
+//# sourceMappingURL=indexer.js.map

package/dist/indexer.js.map

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

package/dist/parser.d.ts

@@ -0,0 +1,38 @@
+/**
+ * YAML parser for koncepto concept files.
+ *
+ * Two-step pipeline:
+ *  1. YAML parse via `yaml` v2 (with size + alias-count guards) → captures syntax errors
+ *  2. Zod validate → captures schema mismatches
+ *
+ * Always returns a structured ParseResult; never throws.
+ *
+ * Security (OWASP A04 Insecure Design): explicit DoS guards on untrusted YAML.
+ *  - MAX_YAML_BYTES caps payload size (rejects >100 KB before parse).
+ *  - MAX_ALIAS_COUNT caps alias expansion (billion-laughs mitigation).
+ * yaml >= 2.8.3 fixes CVE-2026-33532 stack-overflow; these are defense-in-depth
+ * (concept YAML may originate from third-party PRs in OSS context).
+ */
+import { type Concept } from './schema.js';
+export type ParseErrorType = 'yaml_syntax' | 'schema_validation' | 'io_error' | 'unknown';
+export interface ParseError {
+    type: ParseErrorType;
+    message: string;
+    field?: string;
+}
+export interface ParseResult {
+    concept: Concept | null;
+    errors: ParseError[];
+    filePath: string;
+}
+/**
+ * Parse a YAML string in memory.
+ * @param yamlText raw YAML content
+ * @param filePath identifier (no fs read; just metadata for error context)
+ */
+export declare function parseConceptString(yamlText: string, filePath: string): ParseResult;
+/**
+ * Read + parse a YAML concept file from disk.
+ */
+export declare function parseConceptFile(filePath: string): Promise<ParseResult>;
+//# sourceMappingURL=parser.d.ts.map

package/dist/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,aAAa,CAAA;AAKzD,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,mBAAmB,GAAG,UAAU,GAAG,SAAS,CAAA;AAEzF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,cAAc,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IACvB,MAAM,EAAE,UAAU,EAAE,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,CAgDlF;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAiB7E"}

package/dist/parser.js

@@ -0,0 +1,95 @@
+/**
+ * YAML parser for koncepto concept files.
+ *
+ * Two-step pipeline:
+ *  1. YAML parse via `yaml` v2 (with size + alias-count guards) → captures syntax errors
+ *  2. Zod validate → captures schema mismatches
+ *
+ * Always returns a structured ParseResult; never throws.
+ *
+ * Security (OWASP A04 Insecure Design): explicit DoS guards on untrusted YAML.
+ *  - MAX_YAML_BYTES caps payload size (rejects >100 KB before parse).
+ *  - MAX_ALIAS_COUNT caps alias expansion (billion-laughs mitigation).
+ * yaml >= 2.8.3 fixes CVE-2026-33532 stack-overflow; these are defense-in-depth
+ * (concept YAML may originate from third-party PRs in OSS context).
+ */
+import { readFile } from 'node:fs/promises';
+import YAML from 'yaml';
+import { ConceptSchema } from './schema.js';
+const MAX_YAML_BYTES = 100 * 1024; // 100 KB — concepts are small structured docs
+const MAX_ALIAS_COUNT = 50; // explicit billion-laughs / alias-bomb guard
+/**
+ * Parse a YAML string in memory.
+ * @param yamlText raw YAML content
+ * @param filePath identifier (no fs read; just metadata for error context)
+ */
+export function parseConceptString(yamlText, filePath) {
+    // DoS guard 1: byte-size limit (UTF-8) before any parsing work. `string.length`
+    // returns UTF-16 code units, which under-counts multi-byte content.
+    const byteLength = Buffer.byteLength(yamlText, 'utf8');
+    if (byteLength > MAX_YAML_BYTES) {
+        return {
+            concept: null,
+            errors: [
+                {
+                    type: 'yaml_syntax',
+                    message: `YAML exceeds size limit (${byteLength} > ${MAX_YAML_BYTES} bytes)`,
+                },
+            ],
+            filePath,
+        };
+    }
+    let raw;
+    try {
+        // DoS guard 2: cap alias expansion (billion-laughs mitigation).
+        raw = YAML.parse(yamlText, { maxAliasCount: MAX_ALIAS_COUNT });
+    }
+    catch (err) {
+        return {
+            concept: null,
+            errors: [
+                {
+                    type: 'yaml_syntax',
+                    message: err instanceof Error ? err.message : String(err),
+                },
+            ],
+            filePath,
+        };
+    }
+    const result = ConceptSchema.safeParse(raw);
+    if (!result.success) {
+        return {
+            concept: null,
+            errors: result.error.issues.map((issue) => ({
+                type: 'schema_validation',
+                message: issue.message,
+                field: issue.path.length > 0 ? issue.path.join('.') : undefined,
+            })),
+            filePath,
+        };
+    }
+    return { concept: result.data, errors: [], filePath };
+}
+/**
+ * Read + parse a YAML concept file from disk.
+ */
+export async function parseConceptFile(filePath) {
+    let text;
+    try {
+        text = await readFile(filePath, 'utf-8');
+    }
+    catch (err) {
+        return {
+            concept: null,
+            errors: [
+                {
+                    type: 'io_error',
+                    message: err instanceof Error ? err.message : String(err),
+                },
+            ],
+            filePath,
+        };
+    }
+    return parseConceptString(text, filePath);
+}
+//# sourceMappingURL=parser.js.map

package/dist/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,IAAI,MAAM,MAAM,CAAA;AACvB,OAAO,EAAE,aAAa,EAAgB,MAAM,aAAa,CAAA;AAEzD,MAAM,cAAc,GAAG,GAAG,GAAG,IAAI,CAAA,CAAC,8CAA8C;AAChF,MAAM,eAAe,GAAG,EAAE,CAAA,CAAC,6CAA6C;AAgBxE;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB,EAAE,QAAgB;IACnE,gFAAgF;IAChF,oEAAoE;IACpE,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;IACtD,IAAI,UAAU,GAAG,cAAc,EAAE,CAAC;QAChC,OAAO;YACL,OAAO,EAAE,IAAI;YACb,MAAM,EAAE;gBACN;oBACE,IAAI,EAAE,aAAa;oBACnB,OAAO,EAAE,4BAA4B,UAAU,MAAM,cAAc,SAAS;iBAC7E;aACF;YACD,QAAQ;SACT,CAAA;IACH,CAAC;IAED,IAAI,GAAY,CAAA;IAChB,IAAI,CAAC;QACH,gEAAgE;QAChE,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,aAAa,EAAE,eAAe,EAAE,CAAC,CAAA;IAChE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,OAAO,EAAE,IAAI;YACb,MAAM,EAAE;gBACN;oBACE,IAAI,EAAE,aAAa;oBACnB,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;iBAC1D;aACF;YACD,QAAQ;SACT,CAAA;IACH,CAAC;IAED,MAAM,MAAM,GAAG,aAAa,CAAC,SAAS,CAAC,GAAG,CAAC,CAAA;IAC3C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO;YACL,OAAO,EAAE,IAAI;YACb,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBAC1C,IAAI,EAAE,mBAA4B;gBAClC,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;aAChE,CAAC,CAAC;YACH,QAAQ;SACT,CAAA;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAA;AACvD,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,QAAgB;IACrD,IAAI,IAAY,CAAA;IAChB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;IAC1C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,OAAO,EAAE,IAAI;YACb,MAAM,EAAE;gBACN;oBACE,IAAI,EAAE,UAAU;oBAChB,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;iBAC1D;aACF;YACD,QAAQ;SACT,CAAA;IACH,CAAC;IACD,OAAO,kBAAkB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;AAC3C,CAAC"}

package/dist/paths.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Cross-platform path normalization for koncepto.
+ *
+ * YAML files store participant paths as forward-slash relative paths
+ * (Unix-style). On Windows the filesystem returns backslashes; we normalize
+ * everywhere we read/write paths so equality + globs are consistent.
+ */
+/**
+ * Convert all backslashes to forward slashes.
+ * Works on both Windows (`C:\foo\bar` → `C:/foo/bar`) and Unix (no-op).
+ */
+export declare function normalizeForward(p: string): string;
+/**
+ * Resolve a (possibly relative) path against a root, then return a forward-slash
+ * normalized absolute path.
+ */
+export declare function resolveRelative(rootDir: string, relative: string): string;
+/**
+ * Cross-platform basename. Stripped of extension if `stripExt` is true.
+ */
+export declare function basename(p: string, stripExt?: boolean): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGzE;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,UAAQ,GAAG,MAAM,CAK5D"}

package/dist/paths.js

@@ -0,0 +1,34 @@
+/**
+ * Cross-platform path normalization for koncepto.
+ *
+ * YAML files store participant paths as forward-slash relative paths
+ * (Unix-style). On Windows the filesystem returns backslashes; we normalize
+ * everywhere we read/write paths so equality + globs are consistent.
+ */
+import { resolve, basename as nodeBasename, isAbsolute } from 'node:path';
+/**
+ * Convert all backslashes to forward slashes.
+ * Works on both Windows (`C:\foo\bar` → `C:/foo/bar`) and Unix (no-op).
+ */
+export function normalizeForward(p) {
+    return p.replace(/\\/g, '/');
+}
+/**
+ * Resolve a (possibly relative) path against a root, then return a forward-slash
+ * normalized absolute path.
+ */
+export function resolveRelative(rootDir, relative) {
+    const absolute = isAbsolute(relative) ? relative : resolve(rootDir, relative);
+    return normalizeForward(absolute);
+}
+/**
+ * Cross-platform basename. Stripped of extension if `stripExt` is true.
+ */
+export function basename(p, stripExt = false) {
+    const name = nodeBasename(normalizeForward(p));
+    if (!stripExt)
+        return name;
+    const dot = name.lastIndexOf('.');
+    return dot > 0 ? name.slice(0, dot) : name;
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,QAAQ,IAAI,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAEzE;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAS;IACxC,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,QAAgB;IAC/D,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;IAC7E,OAAO,gBAAgB,CAAC,QAAQ,CAAC,CAAA;AACnC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,CAAS,EAAE,QAAQ,GAAG,KAAK;IAClD,MAAM,IAAI,GAAG,YAAY,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAA;IAC9C,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAA;IAC1B,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;IACjC,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AAC5C,CAAC"}

package/dist/schema.d.ts

@@ -0,0 +1,137 @@
+/**
+ * koncepto schema — Zod definitions for the YAML concept format.
+ *
+ * One schema = (1) runtime validator, (2) TypeScript types via z.infer.
+ * See spec § "Schema v0.1" for semantic intent.
+ */
+import { z } from 'zod';
+/**
+ * Kebab-case strict regex for ids (concept id, invariant id, related_concepts).
+ * Lowercase first char, then [a-z0-9-]. No leading/trailing hyphen, no consecutive
+ * separators enforced softly via ^[a-z] start.
+ */
+export declare const KEBAB_ID_REGEX: RegExp;
+export declare const RoleEnum: z.ZodEnum<{
+    writer: "writer";
+    reader: "reader";
+    tester: "tester";
+    docs: "docs";
+}>;
+export type Role = z.infer<typeof RoleEnum>;
+export declare const ConceptTypeEnum: z.ZodEnum<{
+    "behavioral-invariant": "behavioral-invariant";
+    "architectural-decision": "architectural-decision";
+    "data-flow": "data-flow";
+    "ui-pattern": "ui-pattern";
+    "naming-convention": "naming-convention";
+}>;
+export type ConceptType = z.infer<typeof ConceptTypeEnum>;
+export declare const SeverityEnum: z.ZodEnum<{
+    high: "high";
+    medium: "medium";
+    low: "low";
+}>;
+export type Severity = z.infer<typeof SeverityEnum>;
+export declare const StatusEnum: z.ZodEnum<{
+    active: "active";
+    deprecated: "deprecated";
+    superseded: "superseded";
+}>;
+export type Status = z.infer<typeof StatusEnum>;
+export declare const SourceOfTruthSchema: z.ZodObject<{
+    symbol: z.ZodOptional<z.ZodString>;
+    file: z.ZodString;
+}, z.core.$strip>;
+export type SourceOfTruth = z.infer<typeof SourceOfTruthSchema>;
+export declare const ParticipantSchema: z.ZodObject<{
+    file: z.ZodString;
+    role: z.ZodEnum<{
+        writer: "writer";
+        reader: "reader";
+        tester: "tester";
+        docs: "docs";
+    }>;
+    purpose: z.ZodString;
+}, z.core.$strip>;
+export type Participant = z.infer<typeof ParticipantSchema>;
+export declare const InvariantSchema: z.ZodObject<{
+    id: z.ZodString;
+    description: z.ZodString;
+    severity: z.ZodEnum<{
+        high: "high";
+        medium: "medium";
+        low: "low";
+    }>;
+    automated_check: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type Invariant = z.infer<typeof InvariantSchema>;
+export declare const ConceptSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        "behavioral-invariant": "behavioral-invariant";
+        "architectural-decision": "architectural-decision";
+        "data-flow": "data-flow";
+        "ui-pattern": "ui-pattern";
+        "naming-convention": "naming-convention";
+    }>;
+    status: z.ZodDefault<z.ZodEnum<{
+        active: "active";
+        deprecated: "deprecated";
+        superseded: "superseded";
+    }>>;
+    description: z.ZodString;
+    source_of_truth: z.ZodObject<{
+        symbol: z.ZodOptional<z.ZodString>;
+        file: z.ZodString;
+    }, z.core.$strip>;
+    participants: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        role: z.ZodEnum<{
+            writer: "writer";
+            reader: "reader";
+            tester: "tester";
+            docs: "docs";
+        }>;
+        purpose: z.ZodString;
+    }, z.core.$strip>>>;
+    invariants: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+        severity: z.ZodEnum<{
+            high: "high";
+            medium: "medium";
+            low: "low";
+        }>;
+        automated_check: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    risks_if_broken: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    related_concepts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    created: z.ZodString;
+    last_updated: z.ZodString;
+    captured_by: z.ZodOptional<z.ZodString>;
+    references: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type Concept = z.infer<typeof ConceptSchema>;
+export declare const IndexEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        "behavioral-invariant": "behavioral-invariant";
+        "architectural-decision": "architectural-decision";
+        "data-flow": "data-flow";
+        "ui-pattern": "ui-pattern";
+        "naming-convention": "naming-convention";
+    }>;
+    status: z.ZodEnum<{
+        active: "active";
+        deprecated: "deprecated";
+        superseded: "superseded";
+    }>;
+    participants_paths: z.ZodArray<z.ZodString>;
+    tags: z.ZodArray<z.ZodString>;
+    file: z.ZodString;
+}, z.core.$strip>;
+export type IndexEntry = z.infer<typeof IndexEntrySchema>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB;;;;GAIG;AACH,eAAO,MAAM,cAAc,QAAsB,CAAA;AAQjD,eAAO,MAAM,QAAQ;;;;;EAAiD,CAAA;AACtE,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAA;AAE3C,eAAO,MAAM,eAAe;;;;;;EAM1B,CAAA;AACF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAEzD,eAAO,MAAM,YAAY;;;;EAAoC,CAAA;AAC7D,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAA;AAEnD,eAAO,MAAM,UAAU;;;;EAAiD,CAAA;AACxE,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAA;AAI/C,eAAO,MAAM,mBAAmB;;;iBAG9B,CAAA;AACF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAE/D,eAAO,MAAM,iBAAiB;;;;;;;;;iBAI5B,CAAA;AACF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAE3D,eAAO,MAAM,eAAe;;;;;;;;;iBAK1B,CAAA;AACF,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAIvD,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoBxB,CAAA;AACF,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA;AAInD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;iBAQ3B,CAAA;AACF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA"}

package/dist/schema.js

@@ -0,0 +1,74 @@
+/**
+ * koncepto schema — Zod definitions for the YAML concept format.
+ *
+ * One schema = (1) runtime validator, (2) TypeScript types via z.infer.
+ * See spec § "Schema v0.1" for semantic intent.
+ */
+import { z } from 'zod';
+// ─── Identifiers ─────────────────────────────────────────────────────────────
+/**
+ * Kebab-case strict regex for ids (concept id, invariant id, related_concepts).
+ * Lowercase first char, then [a-z0-9-]. No leading/trailing hyphen, no consecutive
+ * separators enforced softly via ^[a-z] start.
+ */
+export const KEBAB_ID_REGEX = /^[a-z][a-z0-9-]+$/;
+const KebabId = z.string().regex(KEBAB_ID_REGEX, {
+    message: 'must be kebab-case (lowercase, [a-z0-9-]+, starts with letter)',
+});
+// ─── Enums ───────────────────────────────────────────────────────────────────
+export const RoleEnum = z.enum(['writer', 'reader', 'tester', 'docs']);
+export const ConceptTypeEnum = z.enum([
+    'behavioral-invariant',
+    'architectural-decision',
+    'data-flow',
+    'ui-pattern',
+    'naming-convention',
+]);
+export const SeverityEnum = z.enum(['high', 'medium', 'low']);
+export const StatusEnum = z.enum(['active', 'deprecated', 'superseded']);
+// ─── Sub-objects ─────────────────────────────────────────────────────────────
+export const SourceOfTruthSchema = z.object({
+    symbol: z.string().min(1).optional(),
+    file: z.string().min(1),
+});
+export const ParticipantSchema = z.object({
+    file: z.string().min(1),
+    role: RoleEnum,
+    purpose: z.string().min(1),
+});
+export const InvariantSchema = z.object({
+    id: KebabId,
+    description: z.string().min(1),
+    severity: SeverityEnum,
+    automated_check: z.boolean().default(false),
+});
+// ─── Concept (top-level) ─────────────────────────────────────────────────────
+export const ConceptSchema = z.object({
+    id: KebabId,
+    name: z.string().min(1),
+    type: ConceptTypeEnum,
+    status: StatusEnum.default('active'),
+    description: z.string().min(1),
+    source_of_truth: SourceOfTruthSchema,
+    participants: z.array(ParticipantSchema).default([]),
+    invariants: z.array(InvariantSchema).default([]),
+    risks_if_broken: z.array(z.string().min(1)).default([]),
+    related_concepts: z.array(KebabId).default([]),
+    tags: z.array(z.string().min(1)).default([]),
+    // Provenance
+    created: z.string().min(1),
+    last_updated: z.string().min(1),
+    captured_by: z.string().optional(),
+    references: z.array(z.string().min(1)).default([]),
+});
+// ─── Index entry (denormalized for fast lookup) ──────────────────────────────
+export const IndexEntrySchema = z.object({
+    id: KebabId,
+    name: z.string().min(1),
+    type: ConceptTypeEnum,
+    status: StatusEnum,
+    participants_paths: z.array(z.string().min(1)),
+    tags: z.array(z.string().min(1)),
+    file: z.string().min(1),
+});
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

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

package/dist/search.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Fuzzy search over IndexEntry list.
+ *
+ * Score model (0-1, higher = better match):
+ *   1.0  exact id match
+ *   0.9  exact tag match
+ *   0.7  case-insensitive substring in id
+ *   0.6  case-insensitive substring in name
+ *   0.5  case-insensitive substring in tag
+ *
+ * Exact matches return early; fuzzy substring scores accumulate.
+ */
+import type { IndexEntry } from './schema.js';
+export type MatchField = 'id' | 'name' | 'tags';
+export interface SearchHit {
+    entry: IndexEntry;
+    score: number;
+    matchedOn: MatchField[];
+}
+export declare function searchEntries(entries: IndexEntry[], query: string, limit?: number): SearchHit[];
+//# sourceMappingURL=search.d.ts.map

package/dist/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAA;AAE/C,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,UAAU,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,UAAU,EAAE,CAAA;CACxB;AAiED,wBAAgB,aAAa,CAC3B,OAAO,EAAE,UAAU,EAAE,EACrB,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAsB,GAC5B,SAAS,EAAE,CAYb"}

package/dist/search.js

@@ -0,0 +1,76 @@
+/**
+ * Fuzzy search over IndexEntry list.
+ *
+ * Score model (0-1, higher = better match):
+ *   1.0  exact id match
+ *   0.9  exact tag match
+ *   0.7  case-insensitive substring in id
+ *   0.6  case-insensitive substring in name
+ *   0.5  case-insensitive substring in tag
+ *
+ * Exact matches return early; fuzzy substring scores accumulate.
+ */
+const DEFAULT_LIMIT = 10;
+// Memoize lowercased projections per entries-array reference. Avoids re-allocating
+// O(N×tags) strings on every search call when the same index is queried repeatedly.
+const loweredCache = new WeakMap();
+function getLowered(entries) {
+    const cached = loweredCache.get(entries);
+    if (cached)
+        return cached;
+    const projected = entries.map((entry) => ({
+        entry,
+        idLower: entry.id.toLowerCase(),
+        nameLower: entry.name.toLowerCase(),
+        tagsLower: entry.tags.map((t) => t.toLowerCase()),
+    }));
+    loweredCache.set(entries, projected);
+    return projected;
+}
+function scoreEntry(lowered, q) {
+    const { entry, idLower, nameLower, tagsLower } = lowered;
+    if (idLower === q) {
+        return { entry, score: 1.0, matchedOn: ['id'] };
+    }
+    if (tagsLower.includes(q)) {
+        return { entry, score: 0.9, matchedOn: ['tags'] };
+    }
+    let score = 0;
+    const matchedOn = [];
+    if (idLower.includes(q)) {
+        score += 0.7;
+        matchedOn.push('id');
+    }
+    if (nameLower.includes(q)) {
+        score += 0.6;
+        matchedOn.push('name');
+    }
+    // Single pass over tags: partial match contributes once.
+    let tagPartial = false;
+    for (const t of tagsLower) {
+        if (t.includes(q)) {
+            tagPartial = true;
+            break;
+        }
+    }
+    if (tagPartial) {
+        score += 0.5;
+        matchedOn.push('tags');
+    }
+    return score > 0 ? { entry, score, matchedOn } : null;
+}
+export function searchEntries(entries, query, limit = DEFAULT_LIMIT) {
+    const q = query.trim().toLowerCase();
+    if (q.length === 0)
+        return [];
+    const lowered = getLowered(entries);
+    const hits = [];
+    for (const item of lowered) {
+        const hit = scoreEntry(item, q);
+        if (hit)
+            hits.push(hit);
+    }
+    hits.sort((a, b) => b.score - a.score);
+    return hits.slice(0, limit);
+}
+//# sourceMappingURL=search.js.map

package/dist/search.js.map

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

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@yourtechtribe-labs/koncept-core",
+  "version": "0.1.0-alpha.1",
+  "description": "Core schema, parser, and indexer for koncepto semantic concept graphs.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "glob": "13.0.6",
+    "yaml": "2.8.4",
+    "zod": "4.4.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/yourtechtribe-labs/koncept-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourtechtribe-labs/koncept-mcp",
+    "directory": "packages/koncept-core"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "echo 'lint stub'",
+    "clean": "rm -rf dist"
+  }
+}