SyncytiumMD

<!--
  ⚠️ AUTO-GENERATED BY SYNCYTIUM-MD ⚠️
  This file is automatically synchronized from .syncytium/
  Do not edit manually unless you plan to run reverse-sync.
  Source of truth: .syncytium/
-->
# GitHub Copilot Instructions for SyncytiumMD

### 🤝 Live Handoff Status
- **Active Agent:** `Antigravity` (Next: `Any`)
- **Status:** `READY_FOR_REVIEW`
- **Current Goal:** Release v0.2.0: correctness, security and extensibility release
- **Pending Tasks:**
  - [ ] Run npm run release to publish v0.2.0
  - [ ] Commit and push the regenerated bridge files
- **Recently Touched:**
  - `.syncytium/architecture.md`
  - `.syncytium/memory/decisions.md`
  - `.syncytium/rules/adapter-standards.md`
  - `.syncytium/HANDOFF.md`
  - `src/core/paths.ts`
  - `src/core/schemas.ts`
  - `src/core/diff.ts`
  - `src/ui/markdown.ts`
- **Notes:** Typecheck, build and 114/114 tests are green. The two known follow-ups are the r128 Three.js CDN pin and the read-only Dockerfile entrypoint.
- **Last Updated:** 2026-09-26T12:21:37.449Z


---

## Architecture Overview

# System Architecture & Technology Stack

> Single source of truth for every AI agent working on this repository. Every
> bridge file (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/*.mdc`, …) is generated
> from this directory by `syncytium sync` — never edit those by hand.

## Overview

SyncytiumMD is a CLI + library + MCP server that maintains one canonical
context (`.syncytium/`) and transpiles it into the native instruction format of
every AI coding tool in use. It also provides multi-agent coordination: a
lease-based workspace lock, a handoff baton with an audit trail, and a local
visual knowledge graph.

## Technology Stack

- **Runtime:** Node.js 22.6+ (ESM, required by `node --experimental-strip-types`)
- **Language:** TypeScript, `strict` plus `noUnusedLocals`,
  `noUnusedParameters`, `noImplicitOverride`, `noImplicitReturns`,
  `verbatimModuleSyntax`
- **Build:** tsup (esbuild) with `dts: true` → `dist/{index,cli/index,mcp/index}.js`
- **CLI:** Commander.js + picocolors
- **Validation:** zod (config schema, rule frontmatter, ADR, every MCP tool input)
- **Parsing:** gray-matter (frontmatter) — all loaders deep-copy, see ADR-006
- **Watching:** chokidar
- **MCP:** `@modelcontextprotocol/sdk` over stdio
- **UI:** zero-dependency `node:http` server + a single-page Three.js app
  (Three.js r128 loaded from cdnjs; the vault/doc panels degrade gracefully
  without it)

## Module Map

| Path | Responsibility |
| --- | --- |
| `src/version.ts` | The single in-code version string; a unit test pins it to `package.json` |
| `src/core/schemas.ts` | Every zod schema: config, rule frontmatter, ADR, handoff, lock, stack |
| `src/core/paths.ts` | `slugify` (path-traversal guard), gitignore-style glob matcher, root containment |
| `src/core/diff.ts` | Dependency-free unified-diff generator used by `diff` |
| `src/core/storage.ts` | `.syncytium/` persistence, config validation/migration, ADR recovery |
| `src/core/templates.ts` | Per-stack rule sets (11 stacks), banners, CI workflow template |
| `src/core/engine.ts` | Orchestrator: init, sync, diff, doctor, lint, handoff, lock, graph, UI server, watch |
| `src/adapters/base.ts` | Shared compile helpers, rule-id sanitising, user-section preservation |
| `src/adapters/registry.ts` | Adapter registry, containment-checked writes, banner-only cleanup |
| `src/adapters/builtin/` | 10 built-in adapters + `GenericAdapter` for config-declared tools |
| `src/ui/markdown.ts` | Canonical Markdown → HTML renderer (injected into the browser bundle) |
| `src/ui/template.ts` | Obsidian Studio HTML: 3D graph, vault explorer, document reader |
| `src/mcp/server.ts` | 18 MCP tools, every input zod-validated, output token-budgeted |
| `src/cli/index.ts` | 22 CLI commands with a global `--json` mode |

## Engine API

`init` · `sync` · `diff` · `doctor` · `lint` · `validate` · `handoff` ·
`getHandoffHistory` · `addDecision` · `removeDecision` · `listDecisions` ·
`addRule` · `getRule` · `removeRule` · `listRules` · `exportBundle` ·
`clean` · `importExisting` · `getStatus` · `acquireLock` · `releaseLock` ·
`renewLock` · `getLockStatus` · `installGitHook` · `uninstallGitHook` ·
`installCiWorkflow` · `uninstallCiWorkflow` · `detectStack` ·
`getKnowledgeGraph` · `startUiServer` · `watch`

## Data Flow

```
.syncytium/  ──load──►  CanonicalContext  ──generate──►  GeneratedFile[]  ──write──►  bridge files
     ▲                                                                                        │
     └────────────────────  diff / prune / preserve user sections  ◄────────────────────────┘
```

`sync` writes every generated file, then prunes banner-tagged files that no rule
produces any more. `diff` compares content and reports `identical`, `modified`
(with a unified patch), `missing_on_disk`, and `unmanaged` (orphans).

## Directory Layout

- `src/` — source code and adapters
- `tests/syncytium.test.ts` — 114 tests, run by `node --experimental-strip-types --test`
- `scripts/release.mjs` — verify → publish → CDN-poll → global install
- `.syncytium/` — single source of truth
  - `rules/` — canonical, stack-aware rules
  - `memory/decisions.md` — ADRs
  - `memory/handoff-history.json` — baton audit trail
  - `memory/lock.json` — machine-local lease (git-ignored)
  - `HANDOFF.md` — live agent state

---

# Engineering Guidelines

## 📌 AI Tool Adapter Guidelines & Architecture
> *Standards for implementing new IDE and CLI bridge adapters in SyncytiumMD*

# AI Tool Adapter Guidelines

When adding or updating adapters in `src/adapters/`:
1. **Interface Contract:**
   - Every adapter must implement `AgentAdapter` from `src/core/types.ts`.
   - Implement `readonly id`, `readonly name`, `readonly category`, `readonly description`, `readonly defaultTargetFiles`.
2. **Deterministic Output:**
   - The `generate(context: CanonicalContext)` method must return an array of `GeneratedFile[]`.
   - Every file must include a leading or trailing SyncytiumMD header comment (e.g. `# Auto-generated by SyncytiumMD`) unless the format forbids comments.
3. **Preserve User Modifications:**
   - Adapters should respect user custom sections where supported.
4. **Registration:**
   - Register all new adapters in `AdapterRegistry` (`src/adapters/registry.ts`).
5. **Coverage:**
   - Add unit tests verifying target file generation in `tests/syncytium.test.ts`.

---

## 📌 Code Style & Formatting
> *Enforce clean, readable, modern standards across the project*

# Code Style & Formatting

- Write clean, modular, and self-documenting code.
- Always prefer strict types, immutable data structures, and pure functions where reasonable.
- Keep functions concise with a single responsibility.
- Preserve existing comments and documentation unless explicitly asked to modify them.
- Avoid unnecessary dependencies; prefer standard library APIs where possible.

## Repository-specific conventions

- **Comments explain *why*.** A comment restating what the code does is noise;
  a comment explaining a non-obvious constraint, a bug workaround, or a
  deliberate deviation is mandatory. Prefer a short comment at the point of
  the decision over a long block at the top of the file.
- **Never let a shared, cached object escape.** `gray-matter` hands back the
  same object for identical content, and `DEFAULT_CONFIG` / `INITIAL_RULES` /
  `INITIAL_DECISIONS` are module-level singletons. Copy before mutating
  (see `clone()` in `src/core/storage.ts` and `deepClone()` in the config path).
- **Order-dependent output is a bug.** Rule loading is sorted explicitly so
  generated files are byte-identical across platforms.
- **Derive, do not duplicate.** The version lives in `src/version.ts`, the
  Markdown renderer in `src/ui/markdown.ts` (injected into the browser bundle
  via `Function.prototype.toString()`), and path safety in `src/core/paths.ts`.
  A second copy will drift.
- When a bug is fixed, add a test that fails without the change and name the
  regression in the test description.

---

## 📌 Release & Verification Criteria
> *Every change ships green: typecheck, build, tests, lint, and zero context drift*

# Release Criteria

A change is not done until all of these pass locally:

```bash
npm run typecheck   # tsc --noEmit over src/ and tests/
npm run build       # tsup, ESM + .d.ts
npm test            # 114 tests, node --experimental-strip-types
npm run verify      # all three, in order
```

## Before opening a PR

- `node dist/cli/index.js lint` — canonical rules and frontmatter are valid.
- `node dist/cli/index.js diff` — **no** drift between `.syncytium/` and the
  committed bridge files. Commit the regenerated files together with the change.
- `node dist/cli/index.js doctor` — no `error` checks. Warnings are acceptable
  only when they are pre-existing and unrelated.

## Releasing

`npm run release` runs the whole pipeline and **fails loudly**:

1. `typecheck` → `build` → `test`
2. `npm publish`
3. polls `npm view` with exponential backoff until the version is served
4. `npm install -g` and verifies the installed version

Never hand-edit `src/version.ts` or `package.json` version independently: a unit
test asserts they match, and `--bump` updates both together.

## Definition of done

- New behaviour has a test that fails without the change.
- Public behaviour changes are reflected in `README.md` **and** `README.tr.md`.
- Architectural decisions go into `.syncytium/memory/decisions.md` via
  `syncytium adr add`.
- The handoff baton is updated before the turn ends:
  `syncytium handoff --from "<agent>" -g "<goal>" -d "<done>" -t "<todo>"`.

---

## 📌 Security & Safe Coding
> *Security rules, secrets handling, and sanitization*

# Security & Boundaries

- The Obsidian Studio server binds to `127.0.0.1` and rejects any request whose
  `Host` header is not a loopback name. This is a DNS-rebinding guard: without
  it, any web page the user has open could read `/api/file` from their
  workspace. `--allow-remote` lifts the guard and must only be used knowingly.
- `Access-Control-Allow-Origin` is `null` (same-origin) by default.
- `/api/file` refuses in-root secrets (`.env*`, `*.pem`, `*.key`, `id_rsa`,
  `.npmrc`, `.netrc`, …) and everything under `.git/`, in addition to the
  path-traversal containment check.
- Rule ids arrive from user-authored frontmatter and are interpolated into
  generated file paths. **Every** path is slugified (`src/core/paths.ts`) and
  every write is re-checked against the workspace root before touching disk.
- The UI escapes `projectName` and all node ids, serialises its bootstrap config
  with `<`/`>`/`&`/U+2028 escaped, and uses event delegation instead of inline
  `onclick` — a hostile rule id in a cloned repo must not be able to run script.
- `syncytium clean` deletes only files carrying the Syncytium banner. A user's
  own `.cursor/rules/my-rule.mdc` is never touched.
- MCP tool inputs are validated with zod before they reach the engine.
- Never log or echo secrets, tokens or full file contents to stdout: stdout is
  the MCP JSON-RPC transport.

---

## 📌 Testing Standards & Verification
> *Quality assurance and test verification guidelines*

**Target Files:** `**/*.test.ts, **/*.test.tsx, **/*.spec.ts, tests/**/*`

## Testing Guidelines
- Write unit tests for all business logic and edge cases.
- Mock external network requests, timers, and heavy I/O in unit test suites.
- Verify tests pass before completing any implementation task.
- Follow the Arrange-Act-Assert pattern for test clarity.

---

## 🧠 Key Decisions (ADR)

- **[ADR-001] Adopt SyncytiumMD as Universal Context Bridge:** Use SyncytiumMD as the single source of truth (.syncytium/) to transpile and synchronize rules, memories, and handoff state across all AI coding tools. _(accepted, 2026-09-19)_
- **[ADR-002] Zero-Heavy-Dependencies Knowledge Graph UI:** Implement an embedded Canvas-based force-directed graph server using native node:http and Server-Sent Events (SSE). _(accepted, 2026-09-19)_
- **[ADR-003] Lease-Based Multi-Agent Collision Prevention Lock:** Introduce syncytium lock with time-expiring leases (e.g. 30-45 minutes) stored in .syncytium/memory/lock.json. _(accepted, 2026-09-19)_
- **[ADR-004] Automated Release Pipeline with NPM CDN Replication Polling:** Implement scripts/release.mjs (npm run release) which verifies tests, publishes, polls npm view with exponential backoff until live, and then installs globally. _(accepted, 2026-09-19)_
- **[ADR-005] High-Performance 3D Knowledge Galaxy with Physics Sleep & Geometry Pooling:** Implement Three.js unit sphere geometry and material caching/pooling, simulation alpha decay with auto-sleeping (0% idle CPU load), LOD lazy text sprite generation, floating hover tooltips, and compact view mode (--compact, --no-files, --no-tags). _(accepted, 2026-09-19)_
- **[ADR-006] Make the drift gate capable of failing:** Add diff --check, which exits 1 on any modified, missing or orphaned file. The CI template and the generated pre-commit hook both call it. doctor additionally inspects the workflow text and warns when it does not use --check, because an existing workflow silently keeps the old no-op behaviour. _(accepted, 2026-09-26)_
- **[ADR-007] Never delete a directory that shares its name with a generated target:** clean now deletes only files carrying the Syncytium banner, file by file, and prunes a directory only once it is actually empty. sync additionally prunes banner-tagged files that the current rule set no longer generates, and diff reports them as 'unmanaged' with the reason. _(accepted, 2026-09-26)_
- **[ADR-008] Escape every value that reaches the browser and stop inlining onclick handlers:** projectName is HTML-escaped; the bootstrap config is serialised with angle brackets, ampersand and the U+2028/9 line separators escaped; the category value is allow-listed; and every node id is escaped and carried in a data-node-id attribute handled by one delegated document listener. No inline handlers and no globals on window remain. _(accepted, 2026-09-26)_
- _…and 4 more in `.syncytium/memory/decisions.md`_