From 618286f06ca33fa5424e3dadde5946454203368d Mon Sep 17 00:00:00 2001 From: Bruno Guidolim Date: Fri, 27 Mar 2026 23:28:51 +0100 Subject: [PATCH] Fix stale references and inaccuracies in docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove prerequisites section from README (pack-level concerns, not engine) - Fix Install/ → Sync/ directory name, remove deleted Manifest.swift section, correct backup description in architecture.md - Remove pack-specific Sosumi troubleshooting, fix brew install command - Add missing check-updates and config commands to docs index --- README.md | 13 ------------- docs/README.md | 2 +- docs/architecture.md | 16 +++------------- docs/troubleshooting.md | 17 +---------------- 4 files changed, 5 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 63b2232..0acfcaa 100644 --- a/README.md +++ b/README.md @@ -48,19 +48,6 @@ mcs doctor That's it. Your MCP servers, plugins, hooks, skills, commands, agents, settings, and templates are all in place. -
-📋 Prerequisites - -- macOS 13+ (Apple Silicon or Intel) -- Xcode Command Line Tools - ```bash - xcode-select --install - ``` -- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code/overview) (`claude`) -- [Homebrew](https://brew.sh) - -
- --- ## The Problem diff --git a/docs/README.md b/docs/README.md index f39a59f..f77acd6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,7 +7,7 @@ Documentation for [Managed Claude Stack (mcs)](../README.md) — a configuration New to mcs? Start here: 1. [Install and Quick Start](../README.md#-quick-start) — Get your first pack running in under 2 minutes -2. [CLI Reference](cli.md) — Complete command reference (`sync`, `pack`, `doctor`, `export`, `cleanup`) +2. [CLI Reference](cli.md) — Complete command reference (`sync`, `pack`, `doctor`, `export`, `cleanup`, `check-updates`, `config`) 3. [Troubleshooting](troubleshooting.md) — Common issues and fixes ## Building Tech Packs diff --git a/docs/architecture.md b/docs/architecture.md index 880b891..22378c0 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -9,8 +9,8 @@ Package.swift # swift-tools-version: 6.0, macOS 13+ Sources/mcs/ CLI.swift # @main entry, version, subcommand registration Core/ # Shared infrastructure - Commands/ # CLI subcommands (sync, doctor, cleanup, pack, export) - Install/ # Installation logic, project configuration, convergence engine + Commands/ # CLI subcommands (sync, doctor, cleanup, pack, export, check-updates, config) + Sync/ # Convergence engine, project configuration, installation logic Export/ # Export wizard (ConfigurationDiscovery, ManifestBuilder, PackWriter) TechPack/ # Tech pack protocol, component model, dependency resolver Templates/ # Template engine and section-based file composition @@ -68,16 +68,6 @@ In the per-project model, `Configurator` (with `ProjectSyncStrategy`) composes ` } ``` -### Manifest (`Core/Manifest.swift`) - -Tracks what mcs has installed globally using three data structures: - -1. **File hashes**: SHA-256 hashes of copied resources at install time -2. **Installed component IDs**: set of component identifiers (e.g., `ios.xcodebuildmcp`) -3. **Installed pack IDs**: set of pack identifiers (e.g., `ios`) - -The manifest covers global-scope installations. Per-project state is tracked separately by `ProjectState`. - ### Project State (`Core/ProjectState.swift`) Per-project state stored as JSON at `/.claude/.mcs-project`. Tracks: @@ -105,7 +95,7 @@ Written by `mcs sync` after convergence. ### Backup (`Core/Backup.swift`) -Every file write goes through the backup system. Before overwriting a file, a timestamped copy is created (e.g., `settings.json.backup.20260222_143000`). The `mcs cleanup` command discovers and deletes these backups. +Before modifying files with user content (e.g., `CLAUDE.local.md`), a timestamped backup is created (e.g., `CLAUDE.local.md.backup.20260222_143000`). Tool-managed files are not backed up since they can be regenerated. The `mcs cleanup` command discovers and deletes these backups. ### Lockfile (`Core/Lockfile.swift`) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 835a262..da27a65 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -49,7 +49,7 @@ If you manage Node.js through nvm or similar, make sure it's available in your P **Fix**: Install Claude Code: ```bash -brew install --cask claude-code +brew install claude-code ``` Verify: @@ -90,21 +90,6 @@ cd /path/to/project mcs sync ``` -### Sosumi not responding - -**Symptom**: Apple documentation search via Sosumi returns errors. - -Sosumi uses HTTP transport (external service at `https://sosumi.ai/mcp`). Check your internet connection and verify the server is registered: -```bash -claude mcp list -``` - -If not registered, re-run sync: -```bash -cd /path/to/project -mcs sync -``` - ## Plugins ### Plugin not enabled