toga-ai 1.0.0

package/knowledge/CONVENTIONS.md

@@ -0,0 +1,117 @@
+# Knowledge Base Conventions
+
+> **Canonical spec.** The `kickoff` and `capture` skills embed this same structure.
+> **Developers never hand-edit anything under `knowledge/`** — the skills create,
+> update, and delete docs and keep `registry.json`, frontmatter, and `INDEX.md`
+> files consistent. This file documents the rules so humans can understand the
+> layout; it is not an editing surface.
+
+## The two axes
+
+1. **Framework first.** Everything app- or framework-related lives under `1.0/` or
+   `2.0/`. These are the two PHP frameworks:
+   - **1.0** — the `App_` framework; core repo **`library`**.
+   - **2.0** — the `_underscore` framework; core repo **`_underscore`**.
+2. **Shared vs. client.** Within a framework, app/feature/architecture knowledge
+   lives under `apps/<repo>/`. Anything specific to a single client lives at the top
+   level under `clients/<client>/` and tags its `framework` in frontmatter.
+
+## Folder layout
+
+```
+knowledge/
+├── CONVENTIONS.md         # this file
+├── registry.json          # repo ↔ project ↔ framework ↔ role ↔ dependsOn
+├── INDEX.md               # auto-generated master index
+├── 1.0/
+│   ├── apps/<repo>/architecture.md + features/*.md
+│   └── standards/*.md     # 1.0 coding standards (App_)
+├── 2.0/
+│   ├── apps/<repo>/architecture.md + features/*.md
+│   └── standards/*.md     # 2.0 coding standards (_underscore)
+└── clients/<client>/
+    ├── profile.md
+    ├── features/*.md      # client-specific feature overrides (link back to apps/)
+    └── workflows/*.md     # client business processes
+```
+
+**App folders are keyed by REPO name** (`worker2`, `_underscore`, `api2`, `library`),
+not project name. The human-friendly project name (e.g. "Worker", "API") is stored in
+`registry.json` and in each doc's `project:` frontmatter.
+
+## registry.json
+
+The shared identity/topology of every repo. Maintained **only by the skills**.
+
+```json
+{ "repo": "worker2", "project": "Worker", "framework": "2.0", "role": "app", "dependsOn": [] }
+```
+
+- `repo` — on-disk repo/folder name (the key; unique).
+- `project` — logical project name.
+- `framework` — `"1.0"` or `"2.0"`.
+- `role` — `"core"` (the framework base every same-framework repo depends on) or `"app"`.
+- `dependsOn` — additional repos this one depends on beyond the framework core
+  (e.g. `api2` may later depend on `apiproxy`).
+
+**Dependency loading:** every repo implicitly depends on its framework's `core` repo
+(`_underscore` for 2.0, `library` for 1.0), plus any transitive `dependsOn`.
+`node knowledge.js deps --repo=<repo>` resolves the full load order.
+
+## Frontmatter (every doc)
+
+```yaml
+---
+title: Creating Worker Actions
+framework: "2.0"          # "1.0" | "2.0"
+repo: worker2             # on-disk repo (matches folder + registry); omit for pure client docs
+project: Worker           # logical project name (from registry)
+client: shared            # "shared" for app docs; a real client slug for client docs
+type: feature             # feature | client-feature | workflow | architecture | standard
+status: active            # active | draft | deprecated
+updated: 2026-06-08
+owners: [jcardinal]
+files:                    # the actual on-disk source paths this doc covers (doc → code bridge)
+  - worker2/Worker/Clickup.php
+  - worker2/Controller/Index.php
+related: []               # relative links to related docs
+---
+```
+
+The `files:` list is what makes "a feature spans many files" a non-issue: the doc
+declares the files it covers, so the doc indexes into the code.
+
+## Document types
+
+- **architecture** — how a repo/framework works overall (one per repo). _Elevated._
+- **feature** — a discrete, shared capability or repeatable workflow within a repo.
+- **client-feature** — a client's customization/override of a shared feature; links
+  back to the shared `apps/<repo>/features/<base>.md`.
+- **workflow** — a client business process.
+- **standard** — a coding standard for a framework. _Elevated._
+
+_Elevated_ docs (architecture, standard) are senior-owned; `capture` flags any change
+to them with ⚠ so the developer knows what they're approving.
+
+## INDEX.md files
+
+Never hand-edited. `node knowledge.js index` regenerates the master `INDEX.md`, each
+`<fw>/apps/<repo>/INDEX.md`, and each `clients/<client>/INDEX.md` from frontmatter, so
+they can never drift from the docs.
+
+## Integrity
+
+`node knowledge.js validate` runs after every `capture` write and enforces:
+registry self-consistency (unique repos, valid framework/role, resolvable `dependsOn`),
+folder ↔ registry agreement, and that each doc's `framework`/`repo`/`project` match its
+location and the registry. A non-zero exit means `capture` must stop and repair before
+reporting success.
+
+## Local paths (NEVER committed)
+
+Absolute paths to each repo are **machine-specific and private to each developer**. They
+are **never** stored in this repo (`registry.json` deliberately contains no paths). Each
+developer's paths live only in **their own computer's Claude memory** (`reference` entries:
+`team-repo-path`, `repo-path-<repo>`), resolved lazily by the skills and asked for by repo
+name only when a session actually needs them. Do not add a path field to `registry.json` or
+any committed doc — if you ever find one, it is a mistake to remove.

package/knowledge/INDEX.md

@@ -0,0 +1,19 @@
+# Knowledge Index
+
+_Auto-generated by `knowledge.js index`. Do not hand-edit._
+
+## 1.0 framework
+
+- **library** (Library) _(framework core)_ — 1 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **worker** (Worker) — 1 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+
+## 2.0 framework
+
+- **_underscore** (_Underscore) _(framework core)_ — 2 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **worker2** (Worker) — 2 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **api2** (API) — 1 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+
+## Clients
+
+_No client knowledge captured yet._
+

package/knowledge/registry.json

@@ -0,0 +1,7 @@
+[
+  { "repo": "_underscore", "project": "_Underscore", "framework": "2.0", "role": "core", "dependsOn": [] },
+  { "repo": "worker2",     "project": "Worker",      "framework": "2.0", "role": "app",  "dependsOn": [] },
+  { "repo": "api2",        "project": "API",         "framework": "2.0", "role": "app",  "dependsOn": [] },
+  { "repo": "library",     "project": "Library",     "framework": "1.0", "role": "core", "dependsOn": [] },
+  { "repo": "worker",      "project": "Worker",      "framework": "1.0", "role": "app",  "dependsOn": [] }
+]

package/knowledge.js

@@ -0,0 +1,384 @@
+#!/usr/bin/env node
+
+/**
+ * knowledge.js — deterministic CRUD + integrity guard for the team knowledge base.
+ *
+ * The `kickoff` and `capture` skills author the prose; this script keeps the
+ * mechanical, error-prone parts honest: searching docs, rebuilding INDEX files
+ * from frontmatter, resolving framework/dependency load sets, and validating
+ * that registry.json, the folder layout, and every doc's frontmatter agree.
+ *
+ * No external dependencies. Works on Windows and Mac. Resolves the knowledge
+ * directory relative to THIS file, so it can be invoked from any cwd:
+ *
+ *   node /path/to/claude/knowledge.js <command> [--flags]
+ *
+ * Commands:
+ *   search   --framework= --repo= --project= --client= --file= --q=
+ *   index
+ *   deps     --repo=<repo>
+ *   validate
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, 'knowledge');
+const REGISTRY = path.join(ROOT, 'registry.json');
+const FRAMEWORKS = ['1.0', '2.0'];
+const DOC_TYPES = ['feature', 'client-feature', 'workflow', 'architecture', 'standard'];
+const ELEVATED_TYPES = ['architecture', 'standard'];
+
+/* ------------------------------------------------------------------ */
+/* small utilities                                                     */
+/* ------------------------------------------------------------------ */
+
+function fail(msg) {
+    console.error('ERROR: ' + msg);
+    process.exitCode = 1;
+}
+
+function parseArgs(argv) {
+    const out = {};
+    for (const arg of argv) {
+        const m = arg.match(/^--([^=]+)=(.*)$/);
+        if (m) out[m[1]] = m[2];
+        else if (arg.startsWith('--')) out[arg.slice(2)] = true;
+    }
+    return out;
+}
+
+function walkMd(dir) {
+    const results = [];
+    if (!fs.existsSync(dir)) return results;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) results.push(...walkMd(full));
+        else if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== 'INDEX.md') {
+            results.push(full);
+        }
+    }
+    return results;
+}
+
+/* ------------------------------------------------------------------ */
+/* minimal frontmatter parser (handles the fields we use)              */
+/* ------------------------------------------------------------------ */
+
+function parseFrontmatter(content) {
+    if (!content.startsWith('---')) return { data: {}, body: content };
+    const end = content.indexOf('\n---', 3);
+    if (end === -1) return { data: {}, body: content };
+    const raw = content.slice(3, end).replace(/^\n/, '');
+    const body = content.slice(end + 4).replace(/^\r?\n/, '');
+    const data = {};
+    const lines = raw.split(/\r?\n/);
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (!line.trim()) { i++; continue; }
+        const m = line.match(/^([A-Za-z0-9_]+):\s*(.*)$/);
+        if (!m) { i++; continue; }
+        const key = m[1];
+        let val = m[2].trim();
+        if (val === '') {
+            // possible block list on following indented "- " lines
+            const arr = [];
+            let j = i + 1;
+            while (j < lines.length && /^\s*-\s+/.test(lines[j])) {
+                arr.push(stripQuotes(lines[j].replace(/^\s*-\s+/, '').trim()));
+                j++;
+            }
+            data[key] = arr;
+            i = j;
+            continue;
+        }
+        if (val.startsWith('[') && val.endsWith(']')) {
+            const inner = val.slice(1, -1).trim();
+            data[key] = inner === '' ? [] : inner.split(',').map(s => stripQuotes(s.trim()));
+        } else {
+            data[key] = stripQuotes(val);
+        }
+        i++;
+    }
+    return { data, body };
+}
+
+function stripQuotes(s) {
+    if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+        return s.slice(1, -1);
+    }
+    return s;
+}
+
+function readDoc(file) {
+    const content = fs.readFileSync(file, 'utf8');
+    const { data, body } = parseFrontmatter(content);
+    return { file, rel: path.relative(ROOT, file).split(path.sep).join('/'), data, body };
+}
+
+function allDocs() {
+    const dirs = [];
+    for (const fw of FRAMEWORKS) dirs.push(path.join(ROOT, fw));
+    dirs.push(path.join(ROOT, 'clients'));
+    const files = dirs.flatMap(walkMd);
+    return files.map(readDoc);
+}
+
+/* ------------------------------------------------------------------ */
+/* registry                                                            */
+/* ------------------------------------------------------------------ */
+
+function loadRegistry() {
+    if (!fs.existsSync(REGISTRY)) return [];
+    try {
+        return JSON.parse(fs.readFileSync(REGISTRY, 'utf8'));
+    } catch (e) {
+        fail('registry.json is not valid JSON: ' + e.message);
+        return [];
+    }
+}
+
+function coreReposFor(registry, framework) {
+    return registry.filter(r => r.framework === framework && r.role === 'core').map(r => r.repo);
+}
+
+/* ------------------------------------------------------------------ */
+/* command: deps                                                       */
+/* ------------------------------------------------------------------ */
+
+function cmdDeps(args) {
+    const registry = loadRegistry();
+    const repo = args.repo;
+    if (!repo) return fail('deps requires --repo=<repo>');
+    const entry = registry.find(r => r.repo === repo);
+    if (!entry) return fail('repo not in registry: ' + repo);
+
+    const seen = new Set();
+    const order = [];
+    // framework core(s) first
+    for (const core of coreReposFor(registry, entry.framework)) {
+        if (!seen.has(core)) { seen.add(core); order.push(core); }
+    }
+    // transitive dependsOn, then the repo itself
+    const visit = (r) => {
+        const e = registry.find(x => x.repo === r);
+        if (!e) return;
+        for (const d of (e.dependsOn || [])) visit(d);
+        if (!seen.has(r)) { seen.add(r); order.push(r); }
+    };
+    visit(repo);
+    console.log(order.join('\n'));
+}
+
+/* ------------------------------------------------------------------ */
+/* command: search                                                     */
+/* ------------------------------------------------------------------ */
+
+function cmdSearch(args) {
+    const docs = allDocs();
+    const q = args.q ? String(args.q).toLowerCase() : null;
+    const matches = docs.filter(d => {
+        if (args.framework && d.data.framework !== args.framework) return false;
+        if (args.repo && d.data.repo !== args.repo) return false;
+        if (args.project && d.data.project !== args.project) return false;
+        if (args.client && d.data.client !== args.client) return false;
+        if (args.file) {
+            const files = d.data.files || [];
+            if (!files.some(f => f.includes(args.file))) return false;
+        }
+        if (q) {
+            const hay = (
+                (d.data.title || '') + ' ' +
+                (d.data.files || []).join(' ') + ' ' +
+                d.body
+            ).toLowerCase();
+            if (!hay.includes(q)) return false;
+        }
+        return true;
+    });
+    for (const m of matches) {
+        console.log(m.rel + '\t' + (m.data.title || '') + '\t' + (m.data.type || ''));
+    }
+}
+
+/* ------------------------------------------------------------------ */
+/* command: index                                                      */
+/* ------------------------------------------------------------------ */
+
+function docRow(d) {
+    const title = d.data.title || path.basename(d.file, '.md');
+    const desc = firstSentence(d.body);
+    const files = (d.data.files || []).join(', ');
+    return `| [${title}](${path.basename(path.dirname(d.file)) === '' ? d.rel : './' + path.relative(path.dirname(d.file), d.file).split(path.sep).join('/')}) | ${desc} | ${files} |`;
+}
+
+function firstSentence(body) {
+    const text = body.replace(/^#.*$/gm, '').replace(/\s+/g, ' ').trim();
+    if (!text) return '';
+    const cut = text.slice(0, 160);
+    const dot = cut.indexOf('. ');
+    return (dot > 0 ? cut.slice(0, dot + 1) : cut).trim();
+}
+
+function writeIndex(file, lines) {
+    fs.writeFileSync(file, lines.join('\n') + '\n');
+}
+
+function cmdIndex() {
+    const registry = loadRegistry();
+    const docs = allDocs();
+
+    // per-repo INDEX.md
+    for (const fw of FRAMEWORKS) {
+        const appsDir = path.join(ROOT, fw, 'apps');
+        if (!fs.existsSync(appsDir)) continue;
+        for (const repo of fs.readdirSync(appsDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name)) {
+            const repoDir = path.join(appsDir, repo);
+            const repoDocs = docs.filter(d => d.file.startsWith(repoDir + path.sep));
+            const entry = registry.find(r => r.repo === repo && r.framework === fw);
+            const lines = [
+                `# ${repo} (${entry ? entry.project : '?'}) — ${fw} knowledge`,
+                '',
+                '| Doc | Summary | Files |',
+                '|-----|---------|-------|',
+                ...repoDocs.map(d => relRow(d, repoDir)),
+            ];
+            writeIndex(path.join(repoDir, 'INDEX.md'), lines);
+        }
+    }
+
+    // per-client INDEX.md
+    const clientsDir = path.join(ROOT, 'clients');
+    if (fs.existsSync(clientsDir)) {
+        for (const client of fs.readdirSync(clientsDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name)) {
+            const clientDir = path.join(clientsDir, client);
+            const clientDocs = docs.filter(d => d.file.startsWith(clientDir + path.sep));
+            const lines = [
+                `# Client: ${client}`,
+                '',
+                '| Doc | Framework | Summary | Files |',
+                '|-----|-----------|---------|-------|',
+                ...clientDocs.map(d => `| [${d.data.title || path.basename(d.file, '.md')}](${relLink(d, clientDir)}) | ${d.data.framework || ''} | ${firstSentence(d.body)} | ${(d.data.files || []).join(', ')} |`),
+            ];
+            writeIndex(path.join(clientDir, 'INDEX.md'), lines);
+        }
+    }
+
+    // master INDEX.md
+    const master = ['# Knowledge Index', '', '_Auto-generated by `knowledge.js index`. Do not hand-edit._', ''];
+    for (const fw of FRAMEWORKS) {
+        master.push(`## ${fw} framework`, '');
+        const fwEntries = registry.filter(r => r.framework === fw);
+        if (fwEntries.length === 0) { master.push('_No repos registered._', ''); continue; }
+        for (const e of fwEntries) {
+            const count = docs.filter(d => d.data.repo === e.repo && d.data.framework === fw).length;
+            const role = e.role === 'core' ? ' _(framework core)_' : '';
+            master.push(`- **${e.repo}** (${e.project})${role} — ${count} doc(s) → [${fw}/apps/${e.repo}/INDEX.md](${fw}/apps/${e.repo}/INDEX.md)`);
+        }
+        master.push('');
+    }
+    const clientNames = fs.existsSync(clientsDir)
+        ? fs.readdirSync(clientsDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name) : [];
+    master.push('## Clients', '');
+    if (clientNames.length === 0) master.push('_No client knowledge captured yet._', '');
+    else { for (const c of clientNames) master.push(`- **${c}** → [clients/${c}/INDEX.md](clients/${c}/INDEX.md)`); master.push(''); }
+    writeIndex(path.join(ROOT, 'INDEX.md'), master);
+
+    console.log('index rebuilt: ' + docs.length + ' doc(s) across ' + registry.length + ' registered repo(s).');
+}
+
+function relLink(d, baseDir) {
+    return path.relative(baseDir, d.file).split(path.sep).join('/');
+}
+function relRow(d, baseDir) {
+    return `| [${d.data.title || path.basename(d.file, '.md')}](${relLink(d, baseDir)}) | ${firstSentence(d.body)} | ${(d.data.files || []).join(', ')} |`;
+}
+
+/* ------------------------------------------------------------------ */
+/* command: validate                                                   */
+/* ------------------------------------------------------------------ */
+
+function cmdValidate() {
+    const registry = loadRegistry();
+    let ok = true;
+    const elevated = [];
+
+    // registry self-consistency
+    const repoSeen = new Set();
+    for (const e of registry) {
+        if (!e.repo) { fail('registry entry missing "repo"'); ok = false; continue; }
+        if (repoSeen.has(e.repo)) { fail('duplicate repo in registry: ' + e.repo); ok = false; }
+        repoSeen.add(e.repo);
+        if (!FRAMEWORKS.includes(e.framework)) { fail(`repo ${e.repo}: invalid framework "${e.framework}"`); ok = false; }
+        if (!['core', 'app'].includes(e.role)) { fail(`repo ${e.repo}: invalid role "${e.role}"`); ok = false; }
+        if (!e.project) { fail(`repo ${e.repo}: missing project name`); ok = false; }
+        for (const d of (e.dependsOn || [])) {
+            if (!registry.find(x => x.repo === d)) { fail(`repo ${e.repo}: dependsOn unknown repo "${d}"`); ok = false; }
+        }
+    }
+
+    // folders ↔ registry
+    for (const fw of FRAMEWORKS) {
+        const appsDir = path.join(ROOT, fw, 'apps');
+        if (!fs.existsSync(appsDir)) continue;
+        for (const repo of fs.readdirSync(appsDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name)) {
+            const entry = registry.find(r => r.repo === repo && r.framework === fw);
+            if (!entry) { fail(`folder ${fw}/apps/${repo} has no matching registry entry`); ok = false; }
+        }
+    }
+
+    // docs frontmatter
+    for (const d of allDocs()) {
+        const required = ['title', 'framework', 'type', 'status', 'project'];
+        for (const f of required) {
+            if (!d.data[f]) { fail(`${d.rel}: missing frontmatter "${f}"`); ok = false; }
+        }
+        if (d.data.type && !DOC_TYPES.includes(d.data.type)) { fail(`${d.rel}: invalid type "${d.data.type}"`); ok = false; }
+        const isClientDoc = d.rel.startsWith('clients/');
+        if (isClientDoc) {
+            if (!d.data.client || d.data.client === 'shared') { fail(`${d.rel}: client doc must set a real "client"`); ok = false; }
+        } else {
+            // framework/apps doc: framework + repo must match the path
+            const parts = d.rel.split('/'); // <fw>/apps/<repo>/...  OR <fw>/standards/...
+            const fw = parts[0];
+            if (d.data.framework !== fw) { fail(`${d.rel}: frontmatter framework "${d.data.framework}" != path "${fw}"`); ok = false; }
+            if (parts[1] === 'apps') {
+                const repo = parts[2];
+                if (d.data.repo !== repo) { fail(`${d.rel}: frontmatter repo "${d.data.repo}" != folder "${repo}"`); ok = false; }
+                const entry = registry.find(r => r.repo === repo && r.framework === fw);
+                if (entry && d.data.project !== entry.project) { fail(`${d.rel}: project "${d.data.project}" != registry "${entry.project}"`); ok = false; }
+            }
+        }
+        if (ELEVATED_TYPES.includes(d.data.type)) elevated.push(d.rel);
+    }
+
+    if (elevated.length) {
+        console.log('ELEVATED (senior-owned) docs:');
+        for (const e of elevated) console.log('  ⚠ ' + e);
+    }
+    if (ok) console.log('validate: OK (' + registry.length + ' repos)');
+    else console.log('validate: FAILED — see errors above');
+}
+
+/* ------------------------------------------------------------------ */
+/* dispatch                                                            */
+/* ------------------------------------------------------------------ */
+
+function main() {
+    const [, , cmd, ...rest] = process.argv;
+    const args = parseArgs(rest);
+    switch (cmd) {
+        case 'search': return cmdSearch(args);
+        case 'index': return cmdIndex();
+        case 'deps': return cmdDeps(args);
+        case 'validate': return cmdValidate();
+        default:
+            console.log('Usage: node knowledge.js <search|index|deps|validate> [--flags]');
+            process.exitCode = 1;
+    }
+}
+
+main();

package/mcp-configs/README.md

@@ -0,0 +1,72 @@
+# MCP Server Configuration
+
+`mcp-configs/mcp-servers.json` is a template listing the MCP servers used by the TOGA team. Copy the servers you want into your project's `.mcp.json` file.
+
+## Available servers
+
+### `github` — `@modelcontextprotocol/server-github`
+
+GitHub integration for Claude Code. Enables:
+- Reading PRs and issues without leaving the editor
+- Code search across repos
+- Creating and reviewing PRs from Claude Code
+
+**Setup:**
+1. Create a GitHub personal access token at https://github.com/settings/tokens
+2. Grant: `repo`, `read:org`, `read:user`
+3. Set the environment variable: `GITHUB_PERSONAL_ACCESS_TOKEN=ghp_...`
+4. Add to your project's `.mcp.json`
+
+### `memory` — `@modelcontextprotocol/server-memory`
+
+Local knowledge graph that persists between Claude Code sessions. This is what makes `/session-save` and `/session-resume` work across sessions and across projects.
+
+**Setup:** No API key or configuration needed. Data is stored in a local SQLite file. Just add the server entry to `.mcp.json`.
+
+**Note:** The memory server stores data per machine. It does not sync between team members — each developer has their own local memory graph.
+
+### `context7` — `@upstash/context7-mcp`
+
+Fetches current documentation for PHP libraries and Composer packages. Useful when working with third-party packages — gets you accurate, up-to-date API docs instead of relying on Claude's training data.
+
+**Setup:** No API key required for basic use. Add to `.mcp.json`.
+
+---
+
+## How to add to a project
+
+In your project root, create or edit `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-memory"]
+    },
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"]
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+The `node scripts/install.js` command copies `mcp-configs/mcp-servers.json` to `.claude/mcp-servers.example.json` in the target project as a reference. You still need to manually merge the servers you want into `.mcp.json`.
+
+---
+
+## Recommended setup per project type
+
+**Active development projects** (worker, worker2, api2): Add `memory` + `github` + `context7`
+
+**Read-only / archive projects**: Add `memory` only (for session resume)
+
+**This knowledge repo itself**: Add `memory` + `github` (for PR-based knowledge contributions)

package/mcp-configs/mcp-servers.json

@@ -0,0 +1,23 @@
+{
+  "_readme": "This file is a template. Copy the servers you want into your project's .mcp.json under the 'mcpServers' key. See mcp-configs/README.md for instructions.",
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
+      },
+      "_description": "GitHub integration: PR reviews, issue tracking, code search across repos. Set GITHUB_PERSONAL_ACCESS_TOKEN in your environment."
+    },
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-memory"],
+      "_description": "Cross-session knowledge graph. Enables /session-save and /session-resume to persist state between Claude Code sessions. No configuration required — data stored locally."
+    },
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"],
+      "_description": "Up-to-date documentation for PHP libraries, Composer packages, and frameworks. Resolves library IDs and fetches current docs. No API key required for basic use."
+    }
+  }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "toga-ai",
+  "version": "1.0.0",
+  "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "knowledge-base",
+    "skills",
+    "toga-technology",
+    "php",
+    "developer-tools"
+  ],
+  "homepage": "https://togatech.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TOGATechnology/claude"
+  },
+  "license": "UNLICENSED",
+  "private": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "toga-ai": "scripts/install.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js --post-install",
+    "validate": "node knowledge.js validate",
+    "index": "node knowledge.js index",
+    "sync": "node sync-skills.js"
+  },
+  "files": [
+    "agents/",
+    "rules/",
+    "skills/",
+    "contexts/",
+    "scripts/",
+    "mcp-configs/",
+    ".claude-plugin/",
+    ".claude/settings.json",
+    "knowledge/",
+    "knowledge.js",
+    "sync-skills.js",
+    "CLAUDE.md"
+  ],
+  "main": "knowledge.js",
+  "devDependencies": {}
+}