@alessandroraffa/tangyr 0.0.2 → 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alessandro Raffa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,120 @@
-# tangyr
+# @alessandroraffa/tangyr
 
-A Software Engineering Discipline for Agent Coding.
+CLI for the Tangyr discipline — install and manage operating kits for AI coding tools.
 
-This package is not yet released. See [github.com/alessandroraffa/tangyr](https://github.com/araffa/tangyr).
+An operating kit is a self-contained package of agents, skills, commands, rules, and templates that implements the Tangyr discipline for a specific AI coding context. The CLI places kit artifacts into the environments consumed by supported tools.
+
+## Install / run
+
+```sh
+npx @alessandroraffa/tangyr <command>
+```
+
+Or install globally:
+
+```sh
+npm install -g @alessandroraffa/tangyr
+tangyr <command>
+```
+
+## Commands
+
+### Kit management
+
+| Command                            | Description                                                                                          |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `tangyr install --kit <name>`      | Install a kit resolved from configured search paths (`kitSearchPaths`/`kit` in `tangyr.config.yaml`) |
+| `tangyr install --kit-path <path>` | Install a kit from an explicit kit root path                                                         |
+| `tangyr uninstall`                 | Remove Tangyr from the target scope                                                                  |
+| `tangyr sync`                      | Synchronize installed kit to the latest version                                                      |
+| `tangyr verify`                    | Check installation integrity against the manifest                                                    |
+| `tangyr cleanup`                   | Remove managed artifacts; delegates to uninstall if manifest exists                                  |
+| `tangyr assess`                    | Pre-installation conflict analysis                                                                   |
+| `tangyr list`                      | Display kits discovered in configured search paths and any installed manifests                       |
+
+### Environment
+
+| Command         | Description                                        |
+| --------------- | -------------------------------------------------- |
+| `tangyr detect` | Detect supported AI tool runtimes                  |
+| `tangyr status` | Show managed artifact status per tool              |
+| `tangyr doctor` | Run environment diagnostics with optional auto-fix |
+| `tangyr probe`  | Probe configured platform paths                    |
+
+### Configuration
+
+| Command           | Description                                           |
+| ----------------- | ----------------------------------------------------- |
+| `tangyr init`     | Create a tangyr.config.yaml interactively             |
+| `tangyr config`   | Display or edit Tangyr configuration                  |
+| `tangyr validate` | Validate the kit against kitFormat 1 conformity rules |
+
+## Global flags
+
+| Flag                         | Description                                                                                           |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `--config <path>`            | Use an explicit configuration file                                                                    |
+| `--kit-path <path>`          | Use an explicit operating kit root                                                                    |
+| `--dry-run`                  | Report actions without modifying files                                                                |
+| `--yes`                      | Skip confirmation prompts                                                                             |
+| `--verbose`                  | Detailed output                                                                                       |
+| `--quiet`                    | Errors only                                                                                           |
+| `--no-color`                 | Disable colors                                                                                        |
+| `--claude-config-dir <path>` | Claude Code global root directory (repeatable). Overrides `claudeCodeGlobalPaths` in the config file. |
+
+## Supported tools
+
+- **Claude Code** — artifacts placed in scope-resolved Claude Code paths
+- **GitHub Copilot** — agents and commands compiled to VS Code user directories
+- **OpenAI Codex** — `AGENTS.md`, agent TOML files, rules, hooks, and MCP compiled to Codex paths
+- **OpenCode** — instructions, agents, commands, skills, and MCP placed in XDG config paths
+- **Cursor** — instructions, subagents, rules, commands, skills, hooks, and MCP
+- **Cline** — instructions, rules, workflows, skills, and MCP
+
+## Quick start
+
+```sh
+# Initialize a configuration in your project
+npx @alessandroraffa/tangyr init
+
+# Install a kit by path (preview with --dry-run first)
+npx @alessandroraffa/tangyr install --kit-path ./path/to/operating-kit --dry-run
+npx @alessandroraffa/tangyr install --kit-path ./path/to/operating-kit
+
+# Check installation status, then sync after a kit update
+npx @alessandroraffa/tangyr status
+npx @alessandroraffa/tangyr sync
+```
+
+## Scope
+
+Every write command accepts `--scope global` or `--scope project`. The CLI flag overrides `config.scope` for that invocation.
+
+| Scope     | Manifest location         | Claude Code artifacts               |
+| --------- | ------------------------- | ----------------------------------- |
+| `global`  | `~/.tangyr/manifest.json` | `~/.claude/`                        |
+| `project` | `.tangyr/manifest.json`   | repo root (`AGENTS.md`, `.claude/`) |
+
+## Multiple Claude Code global roots
+
+If you maintain more than one Claude Code account (e.g. `~/.claude` and `~/.claude-work`), you can keep them identical with a single sync operation.
+
+**Via config** (`tangyr.config.yaml`):
+
+```yaml
+claudeCodeGlobalPaths:
+  - ~/.claude
+  - ~/.claude-work
+```
+
+**Via CLI flag** (repeatable, overrides the config field):
+
+```sh
+tangyr sync --claude-config-dir ~/.claude --claude-config-dir ~/.claude-work
+```
+
+Precedence: `--claude-config-dir` flag > `claudeCodeGlobalPaths` in config > default `~/.claude`.
+
+Per-root artifacts (instructions, agents, skills, commands, rules, output-styles, hooks settings) are written under each root. Shared artifacts (`~/.claude.json` for MCP, `~/.agents/hooks` for hooks) are resolved from the platform default and written once regardless of how many roots are configured.
+
+The manifest records the full set of roots written so that `verify` and `uninstall` operate on all of them.