CLAUDE.md - SyncytiumMD

This project uses SyncytiumMD to bridge context between AI tools.

🤝 Live Handoff Status

• Active Agent: opencode (Next: Human)
• Status: BLOCKED
• Current Goal: v0.3.1 npm publish and MCP Registry listing are blocked on npm OIDC trusted-publisher setup
• Pending Tasks:
  • On npmjs.com add a Trusted Publisher for syncytium-md: GitHub Actions, owner mrcbrbn5361, repo SyncytiumMD, workflow release.yml
  • Re-run Release run 42053623967, then run the MCP Discovery workflow (or re-run 42053623576)
  • Rotate any credential that was pasted into chat earlier
• Recently Touched:
  • .gitattributes
  • src/core/storage.ts
  • server.json
  • src/mcp/safety.ts
  • .github/workflows/release.yml
  • .github/dependabot.yml
  • scripts/build-discovery.mjs
  • .github/workflows/discoverability.yml
• Notes: No npm credential exists locally or in GitHub secrets, so 0.3.1 cannot be published until the npm-side trusted publisher exists. After that, both workflows are idempotent and need no secrets.
• Last Updated: 2026-11-05T15:24:48.885Z

🏗️ Architecture & Stack

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 20+ (ESM, build-first; tests run from dist-tests/)
• 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

Engine API

init · sync · diff · doctor · lint · validate · handoff · getHandoffHistory · addDecision · removeDecision · listDecisions · addRule · getRule · removeRule · listRules · exportBundle · clean · importExisting · getStatus · listTrash · restoreFromTrash · 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).

MCP Safety Model

Every advertised tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) from src/mcp/safety.ts, and the server enforces a per-tool sliding-window call budget in the same module. Destructive tools (remove_rule, remove_decision) default to dryRun: true; an actual delete needs dryRun: false and confirm: true. Before deleting, the engine archives the exact rule/ADR bytes under .syncytium/memory/trash/, and syncytium_restore (plus listTrash/restoreFromTrash in the library) can undo the operation. doctor is read-only: it reports remediation strings but never executes them.

The contract is mechanical, not descriptive: every inputSchema is closed with additionalProperties: false and documents each property, and every stable read tool declares an outputSchema plus matching structuredContent. Mutation is never hidden behind a read annotation — validate is read-only and the separate validate_fix tool performs repairs.

Discovery

server.json describes the npm package to registry.modelcontextprotocol.io, and mcpName in package.json proves npm ownership. .github/workflows/discoverability.yml regenerates llms.txt / llms-full.txt, validates the manifest, and publishes it with GitHub OIDC; no credential is stored in the repository.

Directory Layout

• src/ — source code and adapters
• tests/syncytium.test.ts — 123 tests, build-first (npm run build && tsc -p tsconfig.tests.json && node --test dist-tests/*.test.js)
• 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

Guidelines & Engineering Rules

📌 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:

npm run typecheck   # tsc --noEmit over src/ and tests/
npm run build       # tsup, ESM + .d.ts
npm test            # 129 tests, build-first + dist-tests (Node 20+)
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.
• Every MCP tool declares honest readOnlyHint / destructiveHint / idempotentHint / openWorldHint annotations in src/mcp/safety.ts, and the server enforces a per-tool sliding-window rate limit there. A scanner or gateway can therefore reason about the surface, and a runaway agent loop is stopped in-process even when the client ignores the hints.
• Destructive MCP tools are safe by default: dryRun defaults to true and an actual delete requires dryRun: false and confirm: true.
• Deletions are recoverable. removeRule / removeDecision archive the exact source bytes under .syncytium/memory/trash/ before touching the live file, and syncytium_restore / restoreFromTrash undo the operation.
• syncytium_doctor is strictly read-only. Its fix strings are suggestions; it never runs them, spawns processes, or edits git/CI state.
• 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 7 more in .syncytium/memory/decisions.md