Add structured JSON output for automation

CHANGELOG.md

@@ -10,6 +10,7 @@ All notable changes to this project are documented in this file. The format is b
 
 - Scriptable `title`, `tags`, and `rename` subcommands.
 - Safe rename previews, confirmation, recovery manifests, and an `undo` command.
+- Machine-readable JSON output for every scriptable subcommand.
 - Python 3.11–3.13 test matrix, linting, coverage, and distribution checks.
 
 ### Changed

MANIFEST.in

@@ -0,0 +1 @@
+recursive-include docs *.md

README.md

@@ -37,6 +37,17 @@ creator-toolkit title "video editing"
 creator-toolkit tags --count 5
 ```
 
+Add `--json` to any scriptable subcommand for automation-friendly output:
+
+```bash
+creator-toolkit title "video editing" --json
+creator-toolkit tags --count 5 --json
+creator-toolkit rename ./images --dry-run --json
+```
+
+See the [JSON output reference](https://github.com/HoungDev/creator-toolkit-cli/blob/main/docs/json-output.md)
+for response schemas, exit codes, error handling, and automation examples.
+
 Preview changes to `.jpg`, `.jpeg`, and `.png` files without touching the directory:
 
 ```bash

docs/json-output.md

@@ -0,0 +1,89 @@
+# JSON output
+
+Every scriptable subcommand supports `--json`. Successful responses are written as one JSON
+object to standard output. Runtime and validation errors are written as one JSON object to
+standard error, leaving standard output empty.
+
+## Envelope
+
+Successful responses use this envelope:
+
+```json
+{
+  "schema_version": 1,
+  "command": "tags",
+  "ok": true,
+  "status": "generated",
+  "result": {
+    "count": 2,
+    "tags": ["automation", "python"]
+  }
+}
+```
+
+Errors replace `result` with a stable error object:
+
+```json
+{
+  "schema_version": 1,
+  "command": "rename",
+  "ok": false,
+  "status": "error",
+  "error": {
+    "type": "FileNotFoundError",
+    "message": "Folder not found: ./missing"
+  }
+}
+```
+
+The fields inside `result` depend on the command:
+
+- `title`: `title`.
+- `tags`: `count` and `tags`.
+- `rename`: `directory`, `manifest`, and `operations`.
+- `undo`: `manifest` and `operations`.
+
+Each operation contains `source` and `destination` filenames. Rename statuses are `preview`,
+`unchanged`, or `applied`; undo statuses are `preview` or `restored`.
+
+## Safe non-interactive use
+
+JSON mode never prompts. `rename` and `undo` therefore require either `--dry-run` or `--yes` when
+combined with `--json`. Omitting both produces a structured `UsageError` and exit code 2.
+
+## Exit codes
+
+- `0`: success, including previews and human-confirmed cancellation.
+- `1`: runtime or validation error.
+- `2`: invalid CLI usage or an unsafe JSON-mode invocation.
+
+## Automation examples
+
+Read generated tags from Python:
+
+```python
+import json
+import subprocess
+
+result = subprocess.run(
+    ["creator-toolkit", "tags", "--count", "3", "--json"],
+    check=True,
+    capture_output=True,
+    text=True,
+)
+tags = json.loads(result.stdout)["result"]["tags"]
+print(tags)
+```
+
+Inspect a rename plan from PowerShell without modifying files:
+
+```powershell
+$plan = creator-toolkit rename .\images --dry-run --json | ConvertFrom-Json
+$plan.result.operations | Format-Table source, destination
+```
+
+Apply a previously reviewed rename plan in CI:
+
+```bash
+creator-toolkit rename ./images --yes --json > rename-result.json
+```

pyproject.toml

@@ -37,6 +37,7 @@ creator-toolkit = "creator_toolkit.main:main"
 
 [project.urls]
 Changelog = "https://github.com/HoungDev/creator-toolkit-cli/blob/main/CHANGELOG.md"
+Documentation = "https://github.com/HoungDev/creator-toolkit-cli/tree/main/docs"
 Issues = "https://github.com/HoungDev/creator-toolkit-cli/issues"
 Repository = "https://github.com/HoungDev/creator-toolkit-cli"