repo-context-center 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gökhan Yigit
+
+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,164 @@
+# repo-context-center
+
+A context layer for AI coding agents.
+
+`repo-context-center` installs a small set of repository instructions and context maps into a target repo so AI coding tools can find the right context faster and avoid rereading noisy files.
+
+It is not an AI agent. It is not a code analyzer. It does not understand your project automatically yet. It gives agents a durable place to store routing notes, module maps, risk notes, token guidance, and lessons learned.
+
+It is designed to work with Codex, Claude Code, Cursor, Copilot-style agents, and other tools that read repository instructions.
+
+## What Problem This Solves
+
+AI coding agents often waste context on repeated discovery:
+
+- Which files matter for this task?
+- Which generated folders should be skipped?
+- Where are the risky boundaries?
+- What did the last session already learn?
+- Which docs should be updated after a change?
+
+This project adds a generic Repository Context Center to answer those questions inside the repo.
+
+## Quick Start
+
+From a clone of this project:
+
+```sh
+npm install
+npm run build
+npm link
+```
+
+Then, inside a target repository:
+
+```sh
+repo-context-center init
+repo-context-center validate
+```
+
+Preview installation without writing files:
+
+```sh
+repo-context-center init --dry-run
+```
+
+Overwrite existing context templates:
+
+```sh
+repo-context-center init --force
+```
+
+## Installed Files
+
+`repo-context-center init` installs generic templates:
+
+- `AGENTS.md`
+- `docs/ai-context/COMMUNICATION_MODE.md`
+- `docs/ai-context/TASK_ROUTING.md`
+- `docs/ai-context/MODULE_INDEX.md`
+- `docs/ai-context/PROJECT_MAP.md`
+- `docs/ai-context/RISK_REGISTER.md`
+- `docs/ai-context/DEPENDENCY_MAP.md`
+- `docs/ai-context/SYMBOL_MAP.md`
+- `docs/ai-context/TOKEN_BUDGET.md`
+- `docs/ai-context/DO_NOT_READ.md`
+- `docs/ai-context/HOTSPOTS.md`
+- `docs/ai-context/LESSONS_LEARNED.md`
+- `docs/ai-context/CHANGE_LOG.md`
+- `docs/ai-context/archive/`
+
+It also creates `.repo-context-center/config.json`.
+
+## Commands
+
+```sh
+repo-context-center --help
+repo-context-center init [--dry-run] [--force]
+repo-context-center validate [--strict]
+repo-context-center archive [--keep <number>] [--dry-run]
+```
+
+- `init`: install the generic context templates.
+- `validate`: check that required context files exist and report warnings.
+  Missing `.repo-context-center/config.json` is a warning by default and a
+  failure with `--strict`.
+- `archive`: archive older entries from long-running context files; defaults to keeping 50 entries.
+
+## Recommended AI Agent Workflow
+
+Ask the agent to:
+
+1. Read `AGENTS.md`.
+2. Follow `docs/ai-context/TASK_ROUTING.md`.
+3. Read only the context files relevant to the task.
+4. Check `DO_NOT_READ.md` before broad search.
+5. Update `LESSONS_LEARNED.md` and `CHANGE_LOG.md` when durable context changes.
+
+See [docs/agent-usage.md](docs/agent-usage.md).
+
+## Token-Saving Strategy
+
+The context center is meant to reduce repeated discovery, not replace source reading. It works by keeping small, stable maps near the repo:
+
+- route tasks before opening many files;
+- skip generated and vendored paths by default;
+- keep module, dependency, risk, and symbol notes compact;
+- archive long-running notes before they become noisy.
+
+See [docs/token-strategy.md](docs/token-strategy.md).
+
+## Example: Before/After Session Behavior
+
+Before:
+
+> The agent scans broadly, opens generated files, rediscovers entrypoints, misses a risky shared module, and repeats the same investigation next session.
+
+After:
+
+> The agent reads `AGENTS.md`, follows task routing, opens the relevant module map, checks hotspots, edits a smaller set of files, runs focused tests, and records durable lessons.
+
+More examples are in [docs/examples.md](docs/examples.md).
+
+## Further Reading
+
+- [Concept](docs/concept.md)
+- [Agent usage](docs/agent-usage.md)
+- [Token strategy](docs/token-strategy.md)
+- [Examples](docs/examples.md)
+
+## Supported Project Types
+
+The generic templates are language-agnostic. They can be installed in JavaScript, TypeScript, Python, Go, Rust, Ruby, Java, monorepos, docs repos, and mixed stacks.
+
+Project-specific templates and repo scanning are not implemented yet.
+
+## Roadmap
+
+- Generic template installation and validation.
+- Context file archiving.
+- Project-specific template packs.
+- Optional repository scanning to prefill maps.
+- Safer update workflows for existing context centers.
+
+## Development
+
+```sh
+npm install
+npm run build
+npm test
+```
+
+## Manual Release
+
+This package is prepared for manual npm publishing.
+
+```sh
+npm run build
+npm test
+npm pack
+```
+
+The package publishes the compiled `dist/` output, including the generic context
+templates copied during build. `prepublishOnly` runs build and tests before a
+manual `npm publish`.

package/dist/cli/commands/archive.d.ts

@@ -0,0 +1,2 @@
+import type { CliIO } from "../index";
+export declare function archiveCommand(io: CliIO, args?: string[]): Promise<number>;

package/dist/cli/commands/archive.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.archiveCommand = archiveCommand;
+const archiver_1 = require("../../core/archiver");
+function parseArchiveOptions(args) {
+    const options = {
+        keep: 50,
+        dryRun: false
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--dry-run") {
+            options.dryRun = true;
+            continue;
+        }
+        if (arg === "--keep") {
+            const value = args[index + 1];
+            if (!value) {
+                return undefined;
+            }
+            options.keep = Number(value);
+            index += 1;
+            continue;
+        }
+        return undefined;
+    }
+    if (!Number.isInteger(options.keep) || options.keep < 1) {
+        return undefined;
+    }
+    return options;
+}
+function formatResult(result, dryRun) {
+    const lines = [dryRun ? "Archive dry run" : "Archive complete", ""];
+    for (const file of result.files) {
+        if (file.missing) {
+            lines.push(`Skipped missing optional file: ${file.sourcePath}`);
+            continue;
+        }
+        if (file.archived === 0) {
+            lines.push(`No archive needed: ${file.sourcePath} (${file.kept} entries)`);
+            continue;
+        }
+        const action = dryRun ? "Would archive" : "Archived";
+        lines.push(`${action} ${file.archived} entries from ${file.sourcePath} to ${file.archivePath}`);
+        lines.push(`Kept ${file.kept} entries in ${file.sourcePath}`);
+    }
+    if (dryRun) {
+        lines.push("", "No files were written.");
+    }
+    return `${lines.join("\n")}\n`;
+}
+async function archiveCommand(io, args = []) {
+    const options = parseArchiveOptions(args);
+    if (!options) {
+        io.stderr("Unknown archive option. Supported options: --keep <number>, --dry-run\n");
+        return 1;
+    }
+    const result = await (0, archiver_1.archiveContextFiles)({
+        cwd: io.cwd,
+        keep: options.keep,
+        dryRun: options.dryRun
+    });
+    io.stdout(formatResult(result, options.dryRun));
+    return 0;
+}

package/dist/cli/commands/init.d.ts

@@ -0,0 +1,2 @@
+import type { CliIO } from "../index";
+export declare function initCommand(io: CliIO, args?: string[]): Promise<number>;

package/dist/cli/commands/init.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initCommand = initCommand;
+const config_1 = require("../../core/config");
+const templateInstaller_1 = require("../../core/templateInstaller");
+function parseInitOptions(args) {
+    return {
+        force: args.includes("--force"),
+        dryRun: args.includes("--dry-run")
+    };
+}
+function formatInstallMessage(result, dryRun) {
+    if (dryRun) {
+        if (result.action === "skip") {
+            return `Would skip ${result.type}: ${result.path} already exists\n`;
+        }
+        return `Would ${result.action} ${result.type}: ${result.path}\n`;
+    }
+    if (result.action === "skip") {
+        return `Skipped ${result.type}: ${result.path} already exists\n`;
+    }
+    const verb = result.action === "overwrite" ? "Overwrote" : "Created";
+    return `${verb} ${result.type}: ${result.path}\n`;
+}
+async function initCommand(io, args = []) {
+    const options = parseInitOptions(args);
+    const unknownFlag = args.find((arg) => arg.startsWith("--") && arg !== "--force" && arg !== "--dry-run");
+    if (unknownFlag) {
+        io.stderr(`Unknown init option: ${unknownFlag}\n`);
+        return 1;
+    }
+    const results = await (0, templateInstaller_1.installGenericTemplates)({
+        cwd: io.cwd,
+        force: options.force,
+        dryRun: options.dryRun
+    });
+    for (const result of results) {
+        io.stdout(formatInstallMessage(result, options.dryRun));
+    }
+    if (options.dryRun) {
+        io.stdout("Dry run complete. No files were written.\n");
+        return 0;
+    }
+    if (await (0, config_1.hasConfig)(io.cwd)) {
+        io.stdout(`Config already exists: ${(0, config_1.getConfigPath)(io.cwd)}\n`);
+        return 0;
+    }
+    const configPath = await (0, config_1.writeDefaultConfig)(io.cwd);
+    io.stdout(`Initialized repo-context-center config: ${configPath}\n`);
+    return 0;
+}

package/dist/cli/commands/validate.d.ts

@@ -0,0 +1,2 @@
+import type { CliIO } from "../index";
+export declare function validateCommand(io: CliIO, args?: string[]): Promise<number>;

package/dist/cli/commands/validate.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateCommand = validateCommand;
+const validator_1 = require("../../core/validator");
+function parseValidateOptions(args) {
+    const unknownFlag = args.find((arg) => arg.startsWith("--") && arg !== "--strict");
+    if (unknownFlag) {
+        return undefined;
+    }
+    return {
+        strict: args.includes("--strict")
+    };
+}
+function formatReport(report, strict) {
+    const lines = ["repo-context-center validation report", ""];
+    if (report.missing.length === 0) {
+        lines.push("Required files: ok");
+    }
+    else {
+        lines.push(`Missing required files: ${report.missing.length}`);
+        for (const issue of report.missing) {
+            lines.push(`  - ${issue.path}: ${issue.message}`);
+        }
+    }
+    if (report.warnings.length === 0) {
+        lines.push("Warnings: none");
+    }
+    else {
+        lines.push(`Warnings: ${report.warnings.length}`);
+        for (const issue of report.warnings) {
+            lines.push(`  - ${issue.path}: ${issue.message}`);
+        }
+    }
+    if (report.missing.length > 0) {
+        lines.push("", "Result: failed");
+    }
+    else if (strict && report.warnings.length > 0) {
+        lines.push("", "Result: failed in strict mode");
+    }
+    else {
+        lines.push("", "Result: passed");
+    }
+    return `${lines.join("\n")}\n`;
+}
+async function validateCommand(io, args = []) {
+    const options = parseValidateOptions(args);
+    if (!options) {
+        io.stderr("Unknown validate option. Supported options: --strict\n");
+        return 1;
+    }
+    const report = await (0, validator_1.validateContextSetup)(io.cwd);
+    const hasFailures = report.missing.length > 0 || (options.strict && report.warnings.length > 0);
+    const output = formatReport(report, options.strict);
+    if (hasFailures) {
+        io.stderr(output);
+        return 1;
+    }
+    io.stdout(output);
+    return 0;
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+export interface CliIO {
+    cwd: string;
+    stdout: (message: string) => void;
+    stderr: (message: string) => void;
+}
+export declare function getHelpText(): string;
+export declare function run(argv?: string[], io?: CliIO): Promise<number>;

package/dist/cli/index.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getHelpText = getHelpText;
+exports.run = run;
+const archive_1 = require("./commands/archive");
+const init_1 = require("./commands/init");
+const validate_1 = require("./commands/validate");
+const commands = {
+    init: init_1.initCommand,
+    validate: validate_1.validateCommand,
+    archive: archive_1.archiveCommand
+};
+const helpText = `repo-context-center
+
+Usage:
+  repo-context-center <command>
+
+Commands:
+  init      Install generic context templates and config
+            Options: --dry-run, --force
+  validate  Validate required context files and warnings
+            Options: --strict
+  archive   Archive older CHANGE_LOG and LESSONS_LEARNED entries
+            Options: --keep <number>, --dry-run
+
+Options:
+  -h, --help  Show this help
+`;
+function defaultIO() {
+    return {
+        cwd: process.cwd(),
+        stdout: (message) => process.stdout.write(message),
+        stderr: (message) => process.stderr.write(message)
+    };
+}
+function getHelpText() {
+    return helpText;
+}
+async function run(argv = process.argv.slice(2), io = defaultIO()) {
+    const [command, ...args] = argv;
+    if (!command || command === "--help" || command === "-h") {
+        io.stdout(helpText);
+        return 0;
+    }
+    const handler = commands[command];
+    if (!handler) {
+        io.stderr(`Unknown command: ${command}\n\n${helpText}`);
+        return 1;
+    }
+    return handler(io, args);
+}
+if (require.main === module) {
+    run().then((exitCode) => {
+        process.exitCode = exitCode;
+    }).catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`${message}\n`);
+        process.exitCode = 1;
+    });
+}

package/dist/core/archiver.d.ts

@@ -0,0 +1,16 @@
+export interface ArchiveOptions {
+    cwd: string;
+    keep: number;
+    dryRun?: boolean;
+}
+export interface ArchiveFileResult {
+    sourcePath: string;
+    archivePath: string;
+    kept: number;
+    archived: number;
+    missing: boolean;
+}
+export interface ArchiveResult {
+    files: ArchiveFileResult[];
+}
+export declare function archiveContextFiles(options: ArchiveOptions): Promise<ArchiveResult>;

package/dist/core/archiver.js

@@ -0,0 +1,146 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.archiveContextFiles = archiveContextFiles;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const fileSystem_1 = require("./fileSystem");
+const targetFiles = [
+    {
+        sourcePath: "docs/ai-context/CHANGE_LOG.md",
+        archivePath: "docs/ai-context/archive/CHANGE_LOG_ARCHIVE.md",
+        archiveTitle: "Change Log Archive"
+    },
+    {
+        sourcePath: "docs/ai-context/LESSONS_LEARNED.md",
+        archivePath: "docs/ai-context/archive/LESSONS_LEARNED_ARCHIVE.md",
+        archiveTitle: "Lessons Learned Archive"
+    }
+];
+function isTableRow(line) {
+    return line.trim().startsWith("|") && line.trim().endsWith("|");
+}
+function isDividerRow(line) {
+    return /^\|\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)+\|$/.test(line.trim());
+}
+function splitLines(content) {
+    return content.replace(/\r\n/g, "\n").split("\n");
+}
+function parseFirstTable(content) {
+    const lines = splitLines(content);
+    for (let index = 0; index < lines.length - 1; index += 1) {
+        if (!isTableRow(lines[index]) || !isDividerRow(lines[index + 1])) {
+            continue;
+        }
+        const rows = [];
+        let cursor = index + 2;
+        while (cursor < lines.length && isTableRow(lines[cursor])) {
+            rows.push(lines[cursor]);
+            cursor += 1;
+        }
+        return {
+            before: lines.slice(0, index),
+            header: lines[index],
+            divider: lines[index + 1],
+            rows,
+            after: lines.slice(cursor)
+        };
+    }
+    return undefined;
+}
+function firstCell(row) {
+    return row.split("|")[1]?.trim() ?? "";
+}
+function rowTime(row) {
+    const value = firstCell(row);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        return undefined;
+    }
+    const time = Date.parse(`${value}T00:00:00.000Z`);
+    return Number.isNaN(time) ? undefined : time;
+}
+function selectRows(rows, keep) {
+    const ranked = rows.map((row, index) => ({
+        row,
+        index,
+        time: rowTime(row)
+    }));
+    ranked.sort((left, right) => {
+        if (left.time !== undefined && right.time !== undefined && left.time !== right.time) {
+            return right.time - left.time;
+        }
+        if (left.time !== undefined && right.time === undefined) {
+            return -1;
+        }
+        if (left.time === undefined && right.time !== undefined) {
+            return 1;
+        }
+        return left.index - right.index;
+    });
+    return {
+        keptRows: ranked.slice(0, keep).map((entry) => entry.row),
+        archivedRows: ranked.slice(keep).map((entry) => entry.row)
+    };
+}
+function renderTable(table, rows) {
+    const output = [...table.before, table.header, table.divider, ...rows, ...table.after];
+    return `${output.join("\n").replace(/\n+$/u, "")}\n`;
+}
+function renderArchive(title, table, rows, existingContent) {
+    const existing = existingContent?.trimEnd();
+    const existingTable = existingContent ? parseFirstTable(existingContent) : undefined;
+    if (existing && existingTable) {
+        return renderTable(existingTable, [...existingTable.rows, ...rows]);
+    }
+    if (existing) {
+        return `${existing}\n\n${table.header}\n${table.divider}\n${rows.join("\n")}\n`;
+    }
+    return `# ${title}\n\n${table.header}\n${table.divider}\n${rows.join("\n")}\n`;
+}
+async function archiveFile(target, options) {
+    const sourcePath = node_path_1.default.join(options.cwd, target.sourcePath);
+    const archivePath = node_path_1.default.join(options.cwd, target.archivePath);
+    if (!(await (0, fileSystem_1.pathExists)(sourcePath))) {
+        return {
+            sourcePath: target.sourcePath,
+            archivePath: target.archivePath,
+            kept: 0,
+            archived: 0,
+            missing: true
+        };
+    }
+    const content = await (0, promises_1.readFile)(sourcePath, "utf8");
+    const table = parseFirstTable(content);
+    if (!table || table.rows.length <= options.keep) {
+        return {
+            sourcePath: target.sourcePath,
+            archivePath: target.archivePath,
+            kept: table?.rows.length ?? 0,
+            archived: 0,
+            missing: false
+        };
+    }
+    const { keptRows, archivedRows } = selectRows(table.rows, options.keep);
+    if (!options.dryRun) {
+        const existingArchive = (await (0, fileSystem_1.pathExists)(archivePath)) ? await (0, promises_1.readFile)(archivePath, "utf8") : undefined;
+        await (0, fileSystem_1.writeTextFile)(sourcePath, renderTable(table, keptRows));
+        await (0, fileSystem_1.ensureDir)(node_path_1.default.dirname(archivePath));
+        await (0, fileSystem_1.writeTextFile)(archivePath, renderArchive(target.archiveTitle, table, archivedRows, existingArchive));
+    }
+    return {
+        sourcePath: target.sourcePath,
+        archivePath: target.archivePath,
+        kept: keptRows.length,
+        archived: archivedRows.length,
+        missing: false
+    };
+}
+async function archiveContextFiles(options) {
+    if (!Number.isInteger(options.keep) || options.keep < 1) {
+        throw new Error("--keep must be a positive integer");
+    }
+    const files = await Promise.all(targetFiles.map((target) => archiveFile(target, options)));
+    return { files };
+}

package/dist/core/config.d.ts

@@ -0,0 +1,11 @@
+export interface RepoContextConfig {
+    version: 1;
+    createdBy: "repo-context-center";
+}
+export declare const configDirName = ".repo-context-center";
+export declare const configFileName = "config.json";
+export declare function getConfigPath(cwd: string): string;
+export declare function createDefaultConfig(): RepoContextConfig;
+export declare function hasConfig(cwd: string): Promise<boolean>;
+export declare function writeDefaultConfig(cwd: string): Promise<string>;
+export declare function readConfig(cwd: string): Promise<RepoContextConfig>;

package/dist/core/config.js

@@ -0,0 +1,35 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configFileName = exports.configDirName = void 0;
+exports.getConfigPath = getConfigPath;
+exports.createDefaultConfig = createDefaultConfig;
+exports.hasConfig = hasConfig;
+exports.writeDefaultConfig = writeDefaultConfig;
+exports.readConfig = readConfig;
+const node_path_1 = __importDefault(require("node:path"));
+const fileSystem_1 = require("./fileSystem");
+exports.configDirName = ".repo-context-center";
+exports.configFileName = "config.json";
+function getConfigPath(cwd) {
+    return node_path_1.default.join(cwd, exports.configDirName, exports.configFileName);
+}
+function createDefaultConfig() {
+    return {
+        version: 1,
+        createdBy: "repo-context-center"
+    };
+}
+async function hasConfig(cwd) {
+    return (0, fileSystem_1.pathExists)(getConfigPath(cwd));
+}
+async function writeDefaultConfig(cwd) {
+    const configPath = getConfigPath(cwd);
+    await (0, fileSystem_1.writeJsonFile)(configPath, createDefaultConfig());
+    return configPath;
+}
+async function readConfig(cwd) {
+    return (0, fileSystem_1.readJsonFile)(getConfigPath(cwd));
+}

package/dist/core/contextFiles.d.ts

@@ -0,0 +1,4 @@
+export declare const requiredContextFiles: readonly ["AGENTS.md", "docs/ai-context/COMMUNICATION_MODE.md", "docs/ai-context/TASK_ROUTING.md", "docs/ai-context/MODULE_INDEX.md", "docs/ai-context/PROJECT_MAP.md", "docs/ai-context/RISK_REGISTER.md", "docs/ai-context/DEPENDENCY_MAP.md", "docs/ai-context/SYMBOL_MAP.md", "docs/ai-context/TOKEN_BUDGET.md", "docs/ai-context/DO_NOT_READ.md", "docs/ai-context/HOTSPOTS.md", "docs/ai-context/LESSONS_LEARNED.md", "docs/ai-context/CHANGE_LOG.md"];
+export type RequiredContextFile = (typeof requiredContextFiles)[number];
+export declare const contextArchiveDir = "docs/ai-context/archive";
+export declare const contextSizeLimits: Partial<Record<RequiredContextFile, number>>;

package/dist/core/contextFiles.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contextSizeLimits = exports.contextArchiveDir = exports.requiredContextFiles = void 0;
+const generic_1 = require("../templates/generic");
+exports.requiredContextFiles = generic_1.genericTemplateFiles;
+exports.contextArchiveDir = "docs/ai-context/archive";
+exports.contextSizeLimits = {
+    "docs/ai-context/CHANGE_LOG.md": 32 * 1024,
+    "docs/ai-context/TASK_ROUTING.md": 16 * 1024
+};

package/dist/core/fileSystem.d.ts

@@ -0,0 +1,5 @@
+export declare function pathExists(filePath: string): Promise<boolean>;
+export declare function ensureDir(dirPath: string): Promise<void>;
+export declare function writeJsonFile(filePath: string, value: unknown): Promise<void>;
+export declare function writeTextFile(filePath: string, content: string): Promise<void>;
+export declare function readJsonFile<T>(filePath: string): Promise<T>;

package/dist/core/fileSystem.js

@@ -0,0 +1,35 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pathExists = pathExists;
+exports.ensureDir = ensureDir;
+exports.writeJsonFile = writeJsonFile;
+exports.writeTextFile = writeTextFile;
+exports.readJsonFile = readJsonFile;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+async function pathExists(filePath) {
+    try {
+        await (0, promises_1.access)(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function ensureDir(dirPath) {
+    await (0, promises_1.mkdir)(dirPath, { recursive: true });
+}
+async function writeJsonFile(filePath, value) {
+    await ensureDir(node_path_1.default.dirname(filePath));
+    await (0, promises_1.writeFile)(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+async function writeTextFile(filePath, content) {
+    await ensureDir(node_path_1.default.dirname(filePath));
+    await (0, promises_1.writeFile)(filePath, content, "utf8");
+}
+async function readJsonFile(filePath) {
+    return JSON.parse(await (0, promises_1.readFile)(filePath, "utf8"));
+}

package/dist/core/templateInstaller.d.ts

@@ -0,0 +1,12 @@
+export interface TemplateInstallOptions {
+    cwd: string;
+    force?: boolean;
+    dryRun?: boolean;
+}
+export type TemplateInstallAction = "create" | "overwrite" | "skip";
+export interface TemplateInstallResult {
+    path: string;
+    action: TemplateInstallAction;
+    type: "file" | "directory";
+}
+export declare function installGenericTemplates(options: TemplateInstallOptions): Promise<TemplateInstallResult[]>;

package/dist/core/templateInstaller.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installGenericTemplates = installGenericTemplates;
+const node_path_1 = __importDefault(require("node:path"));
+const fileSystem_1 = require("./fileSystem");
+const generic_1 = require("../templates/generic");
+const archiveDir = "docs/ai-context/archive";
+async function installGenericTemplates(options) {
+    const results = [];
+    const templates = await (0, generic_1.readGenericTemplates)();
+    for (const template of templates) {
+        const targetPath = node_path_1.default.join(options.cwd, template.path);
+        const exists = await (0, fileSystem_1.pathExists)(targetPath);
+        const action = exists ? (options.force ? "overwrite" : "skip") : "create";
+        if (!options.dryRun && action !== "skip") {
+            await (0, fileSystem_1.writeTextFile)(targetPath, template.content);
+        }
+        results.push({ path: template.path, action, type: "file" });
+    }
+    const archivePath = node_path_1.default.join(options.cwd, archiveDir);
+    const archiveExists = await (0, fileSystem_1.pathExists)(archivePath);
+    const archiveAction = archiveExists ? "skip" : "create";
+    if (!options.dryRun && archiveAction === "create") {
+        await (0, fileSystem_1.ensureDir)(archivePath);
+    }
+    results.push({ path: archiveDir, action: archiveAction, type: "directory" });
+    return results;
+}

package/dist/core/validator.d.ts

@@ -0,0 +1,9 @@
+export interface ValidationIssue {
+    path: string;
+    message: string;
+}
+export interface ValidationReport {
+    missing: ValidationIssue[];
+    warnings: ValidationIssue[];
+}
+export declare function validateContextSetup(cwd: string): Promise<ValidationReport>;

package/dist/core/validator.js

@@ -0,0 +1,60 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateContextSetup = validateContextSetup;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const contextFiles_1 = require("./contextFiles");
+const config_1 = require("./config");
+const fileSystem_1 = require("./fileSystem");
+async function getFileSize(filePath) {
+    try {
+        const fileStat = await (0, promises_1.stat)(filePath);
+        return fileStat.isFile() ? fileStat.size : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function validateRequiredFile(cwd, file) {
+    const targetPath = node_path_1.default.join(cwd, file);
+    const fileStat = await getFileSize(targetPath);
+    if (fileStat === undefined) {
+        return {
+            path: file,
+            message: "Required context file is missing"
+        };
+    }
+    return undefined;
+}
+async function validateSize(cwd, file, maxBytes) {
+    const targetPath = node_path_1.default.join(cwd, file);
+    const fileSize = await getFileSize(targetPath);
+    if (fileSize !== undefined && fileSize > maxBytes) {
+        return {
+            path: file,
+            message: `Context file is large (${fileSize} bytes, limit ${maxBytes} bytes)`
+        };
+    }
+    return undefined;
+}
+async function validateContextSetup(cwd) {
+    const missing = (await Promise.all(contextFiles_1.requiredContextFiles.map((file) => validateRequiredFile(cwd, file)))).filter((issue) => issue !== undefined);
+    const sizeWarnings = (await Promise.all(Object.entries(contextFiles_1.contextSizeLimits).map(([file, maxBytes]) => validateSize(cwd, file, maxBytes)))).filter((issue) => issue !== undefined);
+    const warnings = [...sizeWarnings];
+    if (!(await (0, fileSystem_1.pathExists)((0, config_1.getConfigPath)(cwd)))) {
+        warnings.push({
+            path: `${config_1.configDirName}/${config_1.configFileName}`,
+            message: "Config file is missing"
+        });
+    }
+    if (!(await (0, fileSystem_1.pathExists)(node_path_1.default.join(cwd, contextFiles_1.contextArchiveDir)))) {
+        warnings.push({
+            path: contextFiles_1.contextArchiveDir,
+            message: "Archive directory is missing"
+        });
+    }
+    return { missing, warnings };
+}

package/dist/templates/generic/AGENTS.md

@@ -0,0 +1,14 @@
+# AGENTS.md
+
+Use this repository context center before changing code.
+
+Start here:
+- Read `docs/ai-context/COMMUNICATION_MODE.md`.
+- Check `docs/ai-context/TASK_ROUTING.md` for the right path.
+- Read only the context files relevant to the task.
+- Update `LESSONS_LEARNED.md` and `CHANGE_LOG.md` when the work reveals durable facts.
+
+Default rules:
+- Prefer small, reversible changes.
+- Do not scan generated, vendored, or ignored files unless the task requires it.
+- Validate behavior with the narrowest useful test.

package/dist/templates/generic/docs/ai-context/CHANGE_LOG.md

@@ -0,0 +1,15 @@
+# Change Log
+
+Record context-center changes, not every code change.
+
+Format:
+
+| Date | Change | Reason |
+| --- | --- | --- |
+| YYYY-MM-DD | File or section updated | Why context changed |
+
+Use when:
+- A template is installed.
+- A context map is corrected.
+- Routing guidance changes.
+- A stale note is removed.

package/dist/templates/generic/docs/ai-context/COMMUNICATION_MODE.md

@@ -0,0 +1,14 @@
+# Communication Mode
+
+Purpose: align the agent's working style with the current task.
+
+Default mode:
+- Read first, then act.
+- Share assumptions when context is incomplete.
+- Ask only when a wrong assumption would be costly.
+- Keep updates concise and tied to observable progress.
+
+When editing:
+- Name the files being changed.
+- Preserve user changes.
+- Report tests run and failures clearly.

package/dist/templates/generic/docs/ai-context/DEPENDENCY_MAP.md

@@ -0,0 +1,16 @@
+# Dependency Map
+
+Record important internal and external dependencies.
+
+Format:
+
+| From | Depends On | Why It Matters |
+| --- | --- | --- |
+| `module` | `module/package` | Runtime, API, build, or test impact |
+
+Use this to avoid surprise blast radius.
+
+Update when:
+- A shared dependency changes.
+- A module boundary shifts.
+- A new external package is added.

package/dist/templates/generic/docs/ai-context/DO_NOT_READ.md

@@ -0,0 +1,17 @@
+# Do Not Read
+
+Skip these unless the task explicitly requires them.
+
+Common examples:
+- `node_modules/`
+- `dist/`
+- `build/`
+- `coverage/`
+- `.next/`
+- `.turbo/`
+- Generated clients
+- Large snapshots
+- Vendored code
+- Minified bundles
+
+When an excluded file is required, explain why and read the smallest useful section.

package/dist/templates/generic/docs/ai-context/HOTSPOTS.md

@@ -0,0 +1,18 @@
+# Hotspots
+
+Track files or flows that often cause bugs.
+
+Format:
+
+| Hotspot | Why | Safer Move |
+| --- | --- | --- |
+| `path/or/flow` | Failure pattern | Test, review, or constraint |
+
+Use for:
+- Complex state.
+- Concurrency.
+- Auth or permissions.
+- Serialization.
+- Boundary adapters.
+
+Remove entries when they stop being true.

package/dist/templates/generic/docs/ai-context/LESSONS_LEARNED.md

@@ -0,0 +1,19 @@
+# Lessons Learned
+
+Capture durable facts discovered during work.
+
+Format:
+
+| Date | Lesson | Source |
+| --- | --- | --- |
+| YYYY-MM-DD | Short factual note | PR, issue, test, or file |
+
+Good entries:
+- Save future investigation.
+- Explain non-obvious constraints.
+- Point to evidence.
+
+Avoid:
+- Opinions without proof.
+- Temporary task notes.
+- Long narratives.

package/dist/templates/generic/docs/ai-context/MODULE_INDEX.md

@@ -0,0 +1,16 @@
+# Module Index
+
+List important modules and their responsibilities.
+
+Format:
+
+| Path | Owns | Read When |
+| --- | --- | --- |
+| `src/...` | Main behavior or boundary | Task touches this area |
+
+Keep entries short. Prefer stable boundaries over file-by-file detail.
+
+Update when:
+- A module is added, removed, or renamed.
+- Ownership changes.
+- A task repeatedly requires the same context.

package/dist/templates/generic/docs/ai-context/PROJECT_MAP.md

@@ -0,0 +1,17 @@
+# Project Map
+
+Describe the repository at a glance.
+
+Fill in:
+- Primary language/runtime:
+- Package manager:
+- Build command:
+- Test command:
+- Main entrypoints:
+- Generated or vendored paths:
+- Important conventions:
+
+Agent notes:
+- Keep this file factual.
+- Link to files instead of restating long docs.
+- Update when commands or entrypoints change.

package/dist/templates/generic/docs/ai-context/RISK_REGISTER.md

@@ -0,0 +1,18 @@
+# Risk Register
+
+Track areas where changes need extra care.
+
+Format:
+
+| Area | Risk | Check |
+| --- | --- | --- |
+| `path/or/system` | What can break | Test or review needed |
+
+Include:
+- Security-sensitive code.
+- Data migrations.
+- Public APIs.
+- Cross-cutting utilities.
+- Flaky or expensive tests.
+
+Keep risks current and specific.

package/dist/templates/generic/docs/ai-context/SYMBOL_MAP.md

@@ -0,0 +1,17 @@
+# Symbol Map
+
+Track high-value names agents should find quickly.
+
+Format:
+
+| Symbol | Location | Notes |
+| --- | --- | --- |
+| `Name` | `path:line or path` | Role or caller guidance |
+
+Include:
+- Public APIs.
+- Main classes/functions.
+- Config objects.
+- Cross-module types.
+
+Do not list every symbol. Keep this navigational.

package/dist/templates/generic/docs/ai-context/TASK_ROUTING.md

@@ -0,0 +1,18 @@
+# Task Routing
+
+Use this map to choose the smallest useful context set.
+
+Bug fix:
+- Read `PROJECT_MAP.md`, `MODULE_INDEX.md`, `HOTSPOTS.md`, and related tests.
+
+Feature:
+- Read `PROJECT_MAP.md`, `MODULE_INDEX.md`, `DEPENDENCY_MAP.md`, and nearby examples.
+
+Refactor:
+- Read `DEPENDENCY_MAP.md`, `SYMBOL_MAP.md`, and affected callers.
+
+Docs/config:
+- Read `PROJECT_MAP.md` and the target files.
+
+Before broad search:
+- Check `DO_NOT_READ.md`.

package/dist/templates/generic/docs/ai-context/TOKEN_BUDGET.md

@@ -0,0 +1,16 @@
+# Token Budget
+
+Use context deliberately.
+
+Default read order:
+1. `AGENTS.md`
+2. `TASK_ROUTING.md`
+3. Relevant map files
+4. Target source and tests
+
+Avoid:
+- Generated output.
+- Lockfiles unless dependency state matters.
+- Large snapshots or fixtures unless failing behavior depends on them.
+
+Escalate context only when the first pass leaves a concrete unknown.

package/dist/templates/generic/index.d.ts

@@ -0,0 +1,9 @@
+export declare const genericTemplateFiles: readonly ["AGENTS.md", "docs/ai-context/COMMUNICATION_MODE.md", "docs/ai-context/TASK_ROUTING.md", "docs/ai-context/MODULE_INDEX.md", "docs/ai-context/PROJECT_MAP.md", "docs/ai-context/RISK_REGISTER.md", "docs/ai-context/DEPENDENCY_MAP.md", "docs/ai-context/SYMBOL_MAP.md", "docs/ai-context/TOKEN_BUDGET.md", "docs/ai-context/DO_NOT_READ.md", "docs/ai-context/HOTSPOTS.md", "docs/ai-context/LESSONS_LEARNED.md", "docs/ai-context/CHANGE_LOG.md"];
+export type GenericTemplateFile = (typeof genericTemplateFiles)[number];
+export interface TemplateEntry {
+    path: GenericTemplateFile;
+    content: string;
+}
+export declare function getGenericTemplateRoot(): string;
+export declare function readGenericTemplate(file: GenericTemplateFile): Promise<TemplateEntry>;
+export declare function readGenericTemplates(): Promise<TemplateEntry[]>;

package/dist/templates/generic/index.js

@@ -0,0 +1,36 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.genericTemplateFiles = void 0;
+exports.getGenericTemplateRoot = getGenericTemplateRoot;
+exports.readGenericTemplate = readGenericTemplate;
+exports.readGenericTemplates = readGenericTemplates;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+exports.genericTemplateFiles = [
+    "AGENTS.md",
+    "docs/ai-context/COMMUNICATION_MODE.md",
+    "docs/ai-context/TASK_ROUTING.md",
+    "docs/ai-context/MODULE_INDEX.md",
+    "docs/ai-context/PROJECT_MAP.md",
+    "docs/ai-context/RISK_REGISTER.md",
+    "docs/ai-context/DEPENDENCY_MAP.md",
+    "docs/ai-context/SYMBOL_MAP.md",
+    "docs/ai-context/TOKEN_BUDGET.md",
+    "docs/ai-context/DO_NOT_READ.md",
+    "docs/ai-context/HOTSPOTS.md",
+    "docs/ai-context/LESSONS_LEARNED.md",
+    "docs/ai-context/CHANGE_LOG.md"
+];
+function getGenericTemplateRoot() {
+    return __dirname;
+}
+async function readGenericTemplate(file) {
+    const content = await (0, promises_1.readFile)(node_path_1.default.join(getGenericTemplateRoot(), file), "utf8");
+    return { path: file, content };
+}
+async function readGenericTemplates() {
+    return Promise.all(exports.genericTemplateFiles.map((file) => readGenericTemplate(file)));
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "repo-context-center",
+  "version": "0.1.2",
+  "description": "A ContextOps toolkit for AI coding agents.",
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "context",
+    "cli",
+    "repository"
+  ],
+  "author": "Gökhan Yigit",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./dist/cli/index.js",
+  "types": "./dist/cli/index.d.ts",
+  "bin": {
+    "repo-context-center": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/copy-templates.js",
+    "prepublishOnly": "npm run build && npm test",
+    "test": "npm run build && node --test tests/*.test.js"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.2",
+    "typescript": "^5.8.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}