Skip to content

Latest commit

 

History

History
319 lines (234 loc) · 11.6 KB

DOCUMENTATION-INDEX.md

File metadata and controls

319 lines (234 loc) · 11.6 KB

Synaptic Canvas Documentation Index

Last Updated: December 16, 2025 Status: Active Project Version: 0.6.0 (Beta)

This is the central hub for all Synaptic Canvas documentation. Use this index to navigate to the specific information you need.

Quick Navigation

For New Users

For Package Maintainers (Plugin Development)

PLUGIN DEVELOPMENT PATH — Use this checklist when building a plugin:

  1. ✓ Architecture Guidelines — Skill/agent design patterns
  2. ✓ Plugin Storage Conventions — Logs (.claude/state/logs/<pkg>/), settings (.sc/<pkg>/settings.yaml), outputs
  3. ✓ Security Scanning Guide — Validate before release
  4. ✓ Versioning Strategy — Version management
  5. ✓ CONTRIBUTING.md — PR process

Quick Questions?

For Registry Operators

Core Documentation

Project Overview

Document Purpose Audience
README.md Project overview, key features, quick start Everyone
WARP.md Warp terminal integration and startup Terminal users

Development Documentation

Document Purpose Audience
Architecture Guidelines Two-tier pattern, state management, response contracts Plugin Developers
Plugin Storage Conventions Normative: Logs, settings, outputs paths and formats Plugin Developers
Versioning Strategy Three-layer versioning system, SemVer policy Maintainers
CONTRIBUTING.md Contribution guidelines, dev setup, code standards Contributors

Tools and Infrastructure

Document Purpose Location
Plugin Storage Conventions NORMATIVE: Logs, settings, outputs paths/formats (all plugins) docs/PLUGIN-STORAGE-CONVENTIONS.md
Marketplace Infrastructure Complete guide to building and operating Claude Code marketplaces docs/MARKETPLACE-INFRASTRUCTURE.md
Agent Runner Complete guide: features, benefits, integration docs/agent-runner-comprehensive.md
NuGet Integration NuGet-specific documentation docs/nuget/
Registry Metadata Package registry and discovery docs/registries/nuget/

Packages Documentation

Each package in packages/*/ maintains its own documentation:

Available Packages

Package Version Purpose Key Files
sc-delay-tasks 0.4.0 Delayed/polled task execution README
sc-git-worktree 0.4.0 Git worktree management README
sc-manage 0.4.0 Synaptic Canvas package manager README
sc-repomix-nuget 0.4.0 NuGet context generation README
sc-roslyn-diff 0.7.0 Semantic .NET diffs with roslyn-diff README

→ See each package's README.md for details on usage, features, and skills

Version Management

Current Versions

  • Marketplace Platform: 0.4.0 (Beta) — See version.yaml
  • All Packages: 0.4.0 (Beta) — Synchronized for marketplace consistency

Version Tracking

Changelog Files

  • Marketplace: CHANGELOG.md (at repo root) - Platform release history
  • Packages: packages/*/CHANGELOG.md - Per-package release history (coming soon)

Scripts and Tools

Version Management Scripts

Located in scripts/:

Script Purpose Usage
audit-versions.py Verify version consistency across all artifacts ./scripts/audit-versions.py
set-package-version.py Set package versions and regenerate registries python3 scripts/set-package-version.py NAME X.Y.Z
compare-versions.py Compare versions by package python3 scripts/compare-versions.py --by-package

Validation Scripts

Script Purpose Location
validate-agents.py Validate agent frontmatter scripts/validate-agents.py

Architecture

Directory Structure

synaptic-canvas/
├── docs/                          # Documentation hub
│   ├── DOCUMENTATION-INDEX.md     # This file
│   ├── versioning-strategy.md     # Versioning policy
│   ├── registries/                # Registry metadata
│   ├── nuget/                     # NuGet integration docs
│   └── ...
├── packages/                      # Installable packages
│   ├── sc-delay-tasks/               # Package 1
│   ├── sc-git-worktree/              # Package 2
│   ├── sc-manage/                 # Package 3
│   └── sc-repomix-nuget/             # Package 4
├── scripts/                       # Utility scripts
│   ├── audit-versions.py
│   ├── set-package-version.py
│   ├── compare-versions.py
│   └── ...
├── .claude/                       # Claude Code configuration
│   ├── commands/                  # Global commands
│   ├── skills/                    # Global skills
│   ├── agents/                    # Global agents
│   └── scripts/                   # Global helper scripts
├── .archive/                      # Historical/deprecated docs
│   ├── docs/                      # Old documentation
│   └── versioned-docs/            # Historical versions
└── version.yaml                   # Marketplace platform version

Three-Layer Versioning

The project uses three synchronized version layers:

  1. Marketplace Version (version.yaml) - Platform/CLI infrastructure
  2. Package Versions (packages/*/manifest.yaml) - Per-package releases
  3. Artifact Versions (frontmatter in .md files) - Individual components

→ See Versioning Strategy for details

Common Tasks

For Developers

Building a new plugin:

  1. Start with Architecture Guidelines
  2. Review Plugin Storage Conventions for where to read/write data
  3. Use the verification checklist

Installing a package:

python3 tools/sc-install.py install sc-delay-tasks --local

Debugging plugin storage:

# Find logs
ls .claude/state/logs/<package-name>/
cat .claude/state/logs/<package-name>/*.json | jq .

# Find settings
ls .sc/<package-name>/settings.yaml
cat .sc/<package-name>/settings.yaml

# Find outputs
ls -R .sc/<package-name>/output/

Checking version consistency:

./scripts/audit-versions.py

Updating package version:

python3 scripts/set-package-version.py sc-git-worktree 0.5.0

Running tests:

pytest -q

For Contributors

Setting up development environment:

  1. See CONTRIBUTING.md
  2. Create a feature branch: git worktree create feature/branch-name
  3. Make changes and test
  4. Submit PR against main

Adding a new package:

  1. Create packages/new-package/
  2. Add manifest.yaml with version field
  3. Create commands/, skills/, agents/ as needed
  4. Update this index with package info
  5. Add CHANGELOG.md
  6. Commit and test installation

For Maintainers

Releasing a new version:

  1. Update package version in packages/*/manifest.yaml
  2. Run python3 scripts/set-package-version.py name X.Y.Z
  3. Update packages/*/CHANGELOG.md
  4. Run ./scripts/audit-versions.py to verify
  5. Commit with clear message
  6. Create git tag: git tag v0.5.0

Related Resources

External Documentation

  • Claude Code - Official Claude Code documentation (.claude/ commands)
  • Claude Agent SDK - Agent development reference
  • Git Worktrees - Git documentation on worktree functionality

Community

  • Issues - GitHub Issues for bug reports and features
  • Discussions - GitHub Discussions for questions and ideas
  • Contributing - See CONTRIBUTING.md

Documentation Maintenance

Archival Policy

Old or deprecated documentation is moved to .archive/:

  • When to Archive:

    • Documents superseded by newer versions
    • Deprecated guides or outdated patterns
    • Old versions of evolving documents

  • How to Archive:

    1. Move to .archive/ appropriate subdirectory
    2. Update this index with note
    3. Add cross-reference in current docs linking to archived version
    4. Commit with clear archival message

See .archive/README.md for full archival details.

Version Control

This documentation is versioned alongside the marketplace platform:

  • Changes to docs trigger versioning audit in CI/CD
  • Major doc revisions should correspond to version bumps
  • See Versioning Strategy for policy

Quick Help

Can't find what you're looking for?

  1. Search this index for keywords
  2. Check CONTRIBUTING.md for development questions
  3. Review package READMEs in packages/*/
  4. Look in .archive/ for historical information
  5. Check GitHub Issues for known problems

Want to contribute documentation?

  1. Read CONTRIBUTING.md
  2. Edit relevant documentation files
  3. Ensure consistency with this index
  4. Submit PR with clear description

Document Status

Section Status Last Updated
Project Overview ✅ Current Nov 30, 2025
Development Setup ✅ Current Nov 30, 2025
Versioning System ✅ Current Dec 2, 2025
Plugin Storage Conventions ✅ NEW Jan 22, 2026
Package Documentation ✅ Current Dec 1, 2025
Archive Structure ✅ Current Dec 2, 2025
Tools & Scripts ✅ Current Dec 2, 2025
Marketplace Infrastructure ✅ Current Dec 16, 2025

See something outdated? Please open an issue or submit a PR to keep documentation current!