@git.zone/cli 2.14.3 → 2.16.0

package/readme.md

@@ -1,574 +1,410 @@
 # @git.zone/cli 🚀
 
-**The ultimate CLI toolbelt for modern TypeScript development workflows**
+`@git.zone/cli` is the development workflow CLI behind the `gitzone` and `gzone` commands. It helps TypeScript-heavy teams keep projects tidy, create semantic source commits, manage local Docker-backed services, scaffold new modules, and release software through explicit, target-based release configuration.
 
-[![npm version](https://img.shields.io/npm/v/@git.zone/cli.svg)](https://www.npmjs.com/package/@git.zone/cli)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-## 🎯 What is gitzone?
-
-gitzone is a powerful command-line interface that supercharges your development workflow with automated project management, intelligent code formatting, seamless version control, and development service orchestration. Whether you're bootstrapping a new TypeScript project, maintaining code quality, managing complex multi-repository setups, or spinning up local development databases, gitzone has got you covered.
+It is opinionated where that saves time: source commits and releases are separate, changelog entries flow through a standard `Pending` section, project config lives in `.smartconfig.json`, and release targets make side effects visible before they happen.
 
 ## Issue Reporting and Security
 
 For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
 
-## 🏃‍♂️ Quick Start
-
-### Installation
+## Install
 
 ```bash
-# Install globally via pnpm (recommended)
 pnpm add -g @git.zone/cli
-
-# Or with npm
-npm install -g @git.zone/cli
-```
-
-Once installed, you can use either `gitzone` or the shorter `gzone` command from anywhere in your terminal.
-
-### Your First Commands
-
-```bash
-# Create a new TypeScript npm package
-gitzone template npm
-
-# Format your entire codebase (dry-run by default)
-gitzone format
-
-# Apply formatting changes
-gitzone format --write
-
-# Start local MongoDB and MinIO services
-gitzone services start
-
-# Create a semantic commit with AI-powered suggestions
-gitzone commit
 ```
 
-## 🛠️ Core Features
-
-### 🔀 Semantic Commits & Versioning
-
-Create standardized commits with AI-powered suggestions that automatically handle versioning:
+After installation, both binaries point to the same CLI:
 
 ```bash
-# Interactive commit with AI recommendations
-gitzone commit
-
-# Read-only recommendation for agents and scripts
-gitzone commit recommend --json
-
-# Auto-accept AI recommendations (skipped for BREAKING CHANGEs)
-gitzone commit -y
-
-# Auto-accept, push, build, and release
-gitzone commit -ypbr
+gitzone --help
+gzone --help
 ```
 
-**Flags:**
-
-| Flag | Long Form   | Description                              |
-| ---- | ----------- | ---------------------------------------- |
-| `-y` | `--yes`     | Auto-accept AI recommendations           |
-| `-p` | `--push`    | Push to remote after commit              |
-| `-t` | `--test`    | Run tests before committing              |
-| `-b` | `--build`   | Build after commit, verify clean tree    |
-| `-r` | `--release` | Publish to configured npm registries     |
-|      | `--format`  | Run format before committing             |
-|      | `--json`    | Emit JSON for `gitzone commit recommend` |
-
-**Workflow steps:**
+## The Big Idea
 
-1. 🤖 **AI-powered analysis** — analyzes your changes and suggests commit type, scope, and message
-2. 📝 Interactive commit message builder (type: `fix`/`feat`/`BREAKING CHANGE`, scope, description)
-3. 📜 Automatic changelog generation
-4. 🏷️ Automatic version bumping (major/minor/patch) with git tag creation
-5. 🔨 Optional build & verification
-6. 🚀 Optional push to origin
-7. 📦 Optional publish to npm registries
+`gitzone commit` handles source history.
 
-Supports both npm (`package.json`) and Deno (`deno.json`) projects, including dual-type projects.
+`gitzone release` handles release transactions.
 
-### 🎨 Intelligent Code Formatting
+That split is intentional. A commit should not unexpectedly publish npm packages, push Docker images, or trigger remote release pipelines. A release should clearly show which targets it will publish to.
 
-Automatically format and standardize your entire codebase. **Dry-run by default** — nothing changes until you explicitly use `--write`:
+## Quick Start
 
 ```bash
-# Preview what would change (default behavior)
+# Preview project standardization work
 gitzone format
 
-# Emit a machine-readable plan
-gitzone format plan --json
-
-# Apply changes
+# Apply formatting changes
 gitzone format --write
 
-# Auto-approve without prompts
-gitzone format --yes --write
+# Create a semantic source commit
+gitzone commit
 
-# Show detailed diffs
-gitzone format --diff
+# Preview the configured release transaction
+gitzone release --plan
 
-# Enable verbose logging
-gitzone format --verbose
+# Release pending changelog entries to configured targets
+gitzone release
 ```
 
-**Flags:**
-
-| Flag                 | Description                                   |
-| -------------------- | --------------------------------------------- |
-| `--write` / `-w`     | Apply changes (default is dry-run)            |
-| `--yes`              | Auto-approve without interactive confirmation |
-| `--plan-only`        | Only show what would be done                  |
-| `--save-plan <file>` | Save the format plan to a file                |
-| `--from-plan <file>` | Load and execute a saved plan                 |
-| `--detailed`         | Show detailed stats and save report           |
-| `--verbose`          | Enable verbose logging                        |
-| `--diff`             | Show file diffs                               |
-| `--json`             | Emit a read-only format plan as JSON          |
-
-**Formatters (executed in order):**
-
-1. 🧹 **Cleanup** — removes obsolete files (yarn.lock, package-lock.json, tslint.json, etc.)
-2. ⚙️ **Smartconfig** — formats and standardizes `.smartconfig.json`
-3. 📜 **License** — ensures proper licensing and checks dependency licenses
-4. 📦 **Package.json** — standardizes package configuration
-5. 📋 **Templates** — applies project template updates
-6. 🙈 **Gitignore** — updates repository ignore rules
-7. 🔧 **Tsconfig** — optimizes TypeScript configuration
-8. ✨ **Prettier** — applies code formatting
-9. 📖 **Readme** — ensures readme files exist
-10. 📂 **Copy** — copies configured files
-
-### 🐳 Development Services Management
-
-Effortlessly manage local development services (MongoDB, MinIO S3, Elasticsearch) with Docker:
+## Commands
 
-```bash
-gitzone services [command]
-```
+| Command | Purpose |
+| --- | --- |
+| `commit` | Analyze changes and create one semantic source commit |
+| `release` | Turn pending changelog entries into a versioned release and publish targets |
+| `format` | Plan or apply project formatting and standardization |
+| `config` | Inspect, update, and migrate `.smartconfig.json` |
+| `services` | Manage local MongoDB, MinIO, and Elasticsearch containers |
+| `tools` | Manage the global `@git.zone` toolchain |
+| `template` | Scaffold projects from built-in templates |
+| `meta` | Manage multi-repository workspaces |
+| `open` | Open repository assets like CI pages |
+| `docker` | Run Docker maintenance tasks |
+| `deprecate` | Deprecate npm packages across registries |
+| `start` | Prepare an existing project for local work |
+| `helpers` | Run small helper utilities |
 
-**Commands:**
-
-| Command                  | Description                                            |
-| ------------------------ | ------------------------------------------------------ |
-| `start [service]`        | Start services (`mongo`\|`s3`\|`elasticsearch`\|`all`) |
-| `stop [service]`         | Stop services                                          |
-| `restart [service]`      | Restart services                                       |
-| `status`                 | Show current service status                            |
-| `config`                 | Display configuration details                          |
-| `set <csv>`              | Set enabled services without prompts                   |
-| `enable <service...>`    | Enable one or more services                            |
-| `disable <service...>`   | Disable one or more services                           |
-| `compass`                | Get MongoDB Compass connection string with network IP  |
-| `logs [service] [lines]` | View service logs (default: 20 lines)                  |
-| `reconfigure`            | Reassign ports and restart all services                |
-| `remove`                 | Remove containers (preserves data)                     |
-| `clean`                  | Remove containers AND data (⚠️ destructive)            |
-
-**Service aliases:**
-
-- `mongo` / `mongodb` — MongoDB
-- `minio` / `s3` — MinIO (S3-compatible storage)
-- `elasticsearch` / `es` — Elasticsearch
-- `all` — All services (default)
-
-**Key features:**
-
-- 🎲 **Smart port assignment** — automatically assigns random ports (20000–30000) to avoid conflicts
-- 📦 **Project isolation** — each project gets its own containers with unique names
-- 💾 **Data persistence** — data stored in `.nogit/` survives container restarts
-- 🔗 **MongoDB Compass support** — instantly get connection strings for GUI access
-- 🌐 **Network IP detection** — detects your local network IP for remote connections
-- ⚙️ **Auto-configuration** — creates `.nogit/env.json` with smart defaults
-
-**Global operations (`-g` flag):**
+Global flags include `--help`, `--json`, `--plain`, `--agent`, `--no-interactive`, and `--no-check-updates`.
 
-```bash
-# List all registered projects
-gitzone services list -g
+## Toolchain Management
 
-# Show status across all projects
-gitzone services status -g
-
-# Stop all containers across all projects
-gitzone services stop -g
-
-# Remove stale registry entries
-gitzone services cleanup -g
-```
-
-**Example workflow:**
+`gitzone tools` replaces the former `gtools` command from `@git.zone/tools`. It manages globally installed `@git.zone` development tools through pnpm.
 
 ```bash
-# Start all services for your project
-gitzone services start
+# Check installed @git.zone tools and update outdated packages
+gitzone tools update
 
-# Configure enabled services without prompts
-gitzone services set mongodb,minio
-
-# Check what's running
-gitzone services status
-
-# Get MongoDB Compass connection string
-gitzone services compass
-# Output: mongodb://defaultadmin:defaultpass@192.168.1.100:27018/myproject?authSource=admin
+# Update without prompts
+gitzone tools update -y
 
-# View MongoDB logs
-gitzone services logs mongo 50
-
-# Stop services when done
-gitzone services stop
+# Install missing managed @git.zone tools
+gitzone tools install
 ```
 
-### ⚙️ Release & Commit Configuration
+`gitzone tools update` checks `@git.zone/cli` first. If the CLI itself needs an update, it updates `@git.zone/cli` and asks you to rerun the command before updating the rest of the toolchain.
 
-Manage release registries and commit settings:
+## Commit Workflow
 
-```bash
-gitzone config [subcommand]
-```
+`gitzone commit` creates one semantic source commit. It does not bump versions, create tags, publish packages, or push Docker images.
 
-| Command                            | Description                                                |
-| ---------------------------------- | ---------------------------------------------------------- |
-| `show`                             | Display current release config (registries, access level)  |
-| `get <path>`                       | Read a single value from `@git.zone/cli`                   |
-| `set <path> <value>`               | Write a single value to `@git.zone/cli`                    |
-| `unset <path>`                     | Remove a single value from `@git.zone/cli`                 |
-| `add [url]`                        | Add a registry URL (default: `https://registry.npmjs.org`) |
-| `remove [url]`                     | Remove a registry URL (interactive selection if no URL)    |
-| `clear`                            | Clear all registries (with confirmation)                   |
-| `access [public\|private]`         | Set npm access level for publishing                        |
-| `commit alwaysTest [true\|false]`  | Always run tests before commit                             |
-| `commit alwaysBuild [true\|false]` | Always build after commit                                  |
-| `services`                         | Configure which services are enabled                       |
+```bash
+# Interactive semantic commit
+gitzone commit
 
-Configuration is stored in `.smartconfig.json` under the `@git.zone/cli` key.
+# Read-only AI recommendation
+gitzone commit recommend --json
 
-### 📦 Project Templates
+# Auto-accept safe recommendations
+gitzone commit -y
 
-Instantly scaffold production-ready projects with best practices built-in:
+# Auto-accept, test, build, and push
+gitzone commit -ytbp
 
-```bash
-gitzone template [template-name]
+# Show the resolved workflow without mutating anything
+gitzone commit --plan
 ```
 
-**Interactive templates:**
+The commit flow:
 
-- **`npm`** — TypeScript npm package with testing, CI/CD, and full tooling
-- **`service`** — Microservice architecture with Docker support
-- **`website`** — Modern web application with LitElement and service workers
-- **`wcc`** — Web Component Collection for reusable UI components
+1. Analyze the working tree.
+2. Suggest commit type, scope, and message.
+3. Write a human-readable entry into `changelog.md` under `## Pending`.
+4. Stage and create one semantic source commit.
+5. Optionally run formatting, tests, build, and push based on flags or config.
 
-Each template comes pre-configured with:
+Commit flags:
 
-- ✅ TypeScript with modern configurations
-- ✅ Automated testing setup with `@git.zone/tstest`
-- ✅ CI/CD pipelines (GitLab/GitHub)
-- ✅ Code formatting and linting
-- ✅ Documentation structure
+| Flag | Meaning |
+| --- | --- |
+| `-y`, `--yes` | Auto-accept safe recommendations |
+| `-t`, `--test` | Add test step |
+| `-b`, `--build` | Add build step |
+| `-p`, `--push` | Push after the source commit |
+| `-f`, `--format` | Run `gitzone format --write` before commit |
+| `--plan` | Show resolved workflow only |
 
-### 🏗️ Meta Repository Management
+`-r` is intentionally not part of commit anymore. Use `gitzone release`.
 
-Manage multiple related repositories as a cohesive unit:
+## Release Workflow
 
-```bash
-# Initialize a meta repository
-gitzone meta init
+`gitzone release` performs the release core once, then publishes to configured targets.
 
-# Add a sub-project
-gitzone meta add [name] [git-url]
+The release core is not configurable plumbing. It always follows the same professional release transaction:
 
-# Update all sub-projects (clone missing, clean superfluous)
-gitzone meta update
+1. Run configured preflight checks.
+2. Read `changelog.md` `## Pending` entries.
+3. Infer or accept a semver bump.
+4. Update version files and baked commit info.
+5. Move pending changelog entries into the new version section.
+6. Create the local release commit.
+7. Create the local release tag.
 
-# Remove a sub-project
-gitzone meta remove [name]
-```
+Targets decide what happens after that:
 
-### 🐳 Docker Management
-
-Streamline your Docker workflow:
+| Target | What it does |
+| --- | --- |
+| `git` | Pushes the release commit and tags, often triggering remote CI release builds |
+| `npm` | Publishes the package to configured npm registries |
+| `docker` | Builds and pushes configured Docker images |
 
 ```bash
-# Clean up all Docker resources (containers, images, volumes, networks)
-gitzone docker prune
-```
-
-### 🔗 Quick CI/CD Access
+# Preview the resolved release plan
+gitzone release --plan
 
-Jump directly to your CI/CD configurations:
+# Release to configured targets
+gitzone release
 
-```bash
-# Open CI/CD settings
-gitzone open ci
+# Release only to npm
+gitzone release --target npm
 
-# Open pipelines view
-gitzone open pipelines
-```
+# Release only to git and Docker
+gitzone release --target git,docker
 
-Works with GitLab repositories to provide instant access to your deployment configurations.
+# Skip package/container publishing and keep only git target
+gitzone release --no-publish
 
-### 📝 Package Deprecation
+# Override inferred semver level
+gitzone release --minor
+```
 
-Smoothly transition users from old to new packages:
+Release flags:
 
-```bash
-gitzone deprecate
-```
+| Flag | Meaning |
+| --- | --- |
+| `-y`, `--yes` | Run without interactive confirmation |
+| `-t`, `--test` | Enable preflight tests |
+| `-b`, `--build` | Enable preflight build |
+| `-p`, `--push` | Enable the `git` target |
+| `--target <csv>` | Use only selected targets, e.g. `git,npm` |
+| `--npm` | Enable the `npm` target |
+| `--docker` | Enable the `docker` target |
+| `--no-publish` | Keep release core and `git` target only |
+| `--no-build` | Disable preflight build for this run |
+| `--major`, `--minor`, `--patch` | Override inferred semver level |
+| `--plan` | Show resolved workflow only |
 
-Interactive wizard that prompts for registry URLs, old package name, and new package name — then runs `npm deprecate` across all specified registries.
+## Standard Changelog
 
-### 🚦 Project Initialization
+The changelog is convention-based and intentionally not configured.
 
-Prepare existing projects for development:
+`gitzone commit` appends entries to:
 
-```bash
-gitzone start
+```markdown
+## Pending
 ```
 
-Automatically checks out master, pulls latest changes, and installs dependencies.
-
-### 🔧 Helper Utilities
+`gitzone release` moves those pending entries into a dated version section:
 
-```bash
-# Generate a unique short ID
-gitzone helpers shortid
+```markdown
+## 2026-05-10 - 2.15.0
 ```
 
-## 📋 Configuration
+The standard buckets are `Breaking Changes`, `Features`, `Fixes`, `Documentation`, and `Maintenance`.
 
-### .smartconfig.json
+## Configuration
 
-Customize gitzone behavior through `.smartconfig.json`:
+All CLI config lives under `@git.zone/cli` in `.smartconfig.json`.
 
 ```json
 {
   "@git.zone/cli": {
+    "schemaVersion": 2,
     "projectType": "npm",
-    "cli": {
-      "interactive": true,
-      "output": "human",
-      "checkUpdates": true
-    },
-    "release": {
-      "registries": ["https://registry.npmjs.org"],
-      "accessLevel": "public"
-    },
     "commit": {
-      "alwaysTest": false,
-      "alwaysBuild": false
+      "confirmation": "prompt",
+      "steps": ["analyze", "test", "build", "changelog", "commit", "push"]
     },
-    "format": {
-      "interactive": true,
-      "showStats": true,
-      "modules": {
-        "skip": ["prettier"],
-        "only": []
+    "release": {
+      "confirmation": "prompt",
+      "preflight": {
+        "requireCleanTree": true,
+        "test": false,
+        "build": true
+      },
+      "targets": {
+        "git": {
+          "enabled": true,
+          "remote": "origin",
+          "pushBranch": true,
+          "pushTags": true
+        },
+        "npm": {
+          "enabled": true,
+          "registries": ["https://registry.npmjs.org"],
+          "accessLevel": "public",
+          "alreadyPublished": "success"
+        },
+        "docker": {
+          "enabled": false,
+          "images": []
+        }
       }
     }
   }
 }
 ```
 
-### Environment Variables
+NPM registries belong only here:
 
-- `CI` — Detect CI environment for automated workflows
-- `DEBUG` — Enable debug output
-- `GITZONE_FORMAT_PARALLEL` — Control parallel formatting
-
-## 🎯 Common Workflows
+```text
+@git.zone/cli.release.targets.npm.registries
+```
 
-### Full-Stack Development Cycle
+Useful config commands:
 
 ```bash
-# 1. Start fresh
-gitzone start
-
-# 2. Spin up databases and services
-gitzone services start
+# Show current @git.zone/cli config
+gitzone config show --json
 
-# 3. Make changes
-# ... your development work ...
+# Read the npm release target registries
+gitzone config get release.targets.npm.registries
 
-# 4. Check service logs if needed
-gitzone services logs mongo
+# Add an npm release target registry
+gitzone config add https://registry.npmjs.org
 
-# 5. Preview format changes, then apply
-gitzone format
-gitzone format --write
+# Set npm target access level
+gitzone config access public
 
-# 6. Commit with semantic versioning
-gitzone commit
-
-# 7. Stop services when done
-gitzone services stop
+# Run schema migration to v2
+gitzone config migrate 2
 ```
 
-### Automated CI/CD Commit
+## Formatting
 
-```bash
-# Auto-accept, test, build, push, and release in one command
-gitzone commit -ytbpr
-```
-
-### Agent-Friendly Inspection
+`gitzone format` is dry-run by default. That makes it safe to run in any repo.
 
 ```bash
-# Top-level machine-readable help
-gitzone help config --json
-
-# Read-only commit recommendation
-gitzone commit recommend --json
+# Preview changes
+gitzone format
 
-# Read-only format plan
+# Emit a machine-readable plan
 gitzone format plan --json
 
-# Read or change config without prompts
-gitzone config get release.accessLevel
-gitzone config set cli.interactive false
-```
-
-### Multi-Repository Management
-
-```bash
-# 1. Set up meta repository
-gitzone meta init
-
-# 2. Add all related projects
-gitzone meta add frontend https://github.com/org/frontend.git
-gitzone meta add backend https://github.com/org/backend.git
-gitzone meta add shared https://github.com/org/shared.git
+# Apply changes
+gitzone format --write
 
-# 3. Synchronize updates
-gitzone meta update
+# Apply without prompt
+gitzone format --write --yes
 ```
 
-### Safe Formatting with Plan Review
+Formatters include cleanup, smartconfig normalization, dependency license checks, package metadata normalization, template updates, `.gitignore`, TypeScript config, Prettier, README existence checks, and configured copy operations.
 
-```bash
-# 1. Preview changes (default)
-gitzone format
+## Development Services
 
-# 2. Save plan for review
-gitzone format --save-plan format-changes.json
+`gitzone services` manages local Docker-backed services for development projects.
 
-# 3. Apply from saved plan
-gitzone format --from-plan format-changes.json --write
-```
+Supported services:
 
-### Database-Driven Development
+| Service | Aliases |
+| --- | --- |
+| MongoDB | `mongo`, `mongodb` |
+| MinIO | `minio`, `s3` |
+| Elasticsearch | `elasticsearch`, `es` |
 
 ```bash
-# 1. Start MongoDB, MinIO, and Elasticsearch
+# Start configured services
 gitzone services start
 
-# 2. Get connection details
-gitzone services config
+# Enable specific services non-interactively
+gitzone services set mongodb,minio
+
+# Check status
+gitzone services status
 
-# 3. Connect with MongoDB Compass
+# Print MongoDB Compass connection string
 gitzone services compass
 
-# 4. Monitor services
-gitzone services status
+# Show logs
+gitzone services logs mongo 50
 
-# 5. Clean everything when done
-gitzone services clean  # ⚠️ Warning: deletes data
+# Stop containers but keep data
+gitzone services stop
+
+# Remove containers and data
+gitzone services clean
 ```
 
-## 🔌 Integrations
+Service config is stored in `.nogit/env.json`. Data is stored below `.nogit/`, so it stays out of Git.
 
-### CI/CD Platforms
+## Templates
 
-- **GitLab CI** — full pipeline support with templates
-- **GitHub Actions** — automated workflows
-- **Docker** — container-based deployments
+Start new projects with built-in scaffolds:
 
-### Development Tools
+```bash
+gitzone template npm
+gitzone template service
+gitzone template website
+gitzone template wcc
+```
 
-- **TypeScript** — first-class support
-- **Prettier** — code formatting
-- **pnpm** — package management
-- **MongoDB** — local database service
-- **MinIO** — S3-compatible object storage
-- **Elasticsearch** — search and analytics
-- **MongoDB Compass** — database GUI integration
+Templates are rendered through SmartScaf and then can be normalized with `gitzone format`.
 
-### Version Control
+## Meta Repositories
 
-- **Git** — deep integration
-- **Semantic Versioning** — automatic version bumping
-- **Conventional Commits** — standardized commit messages
-- **AI-Powered Analysis** — intelligent commit suggestions via `@git.zone/tsdoc`
+Use `gitzone meta` when one workspace coordinates multiple repositories.
 
-## 💡 Pro Tips
+```bash
+gitzone meta init
+gitzone meta add frontend https://example.com/org/frontend.git
+gitzone meta update
+gitzone meta remove frontend
+```
 
-1. **Use aliases**: Add `alias gz='gitzone'` to your shell profile
-2. **Combine flags**: `gitzone commit -ypbr` for the full auto workflow
-3. **Leverage templates**: Start projects right with proven structures
-4. **Enable caching**: Dramatically speeds up formatting operations
-5. **Save format plans**: Review changes before applying
-6. **Port management**: Let services auto-assign ports to avoid conflicts
-7. **Use MongoDB Compass**: `gitzone services compass` for visual DB management
-8. **Global service management**: `gitzone services status -g` to see all projects' services at once
+## Other Utilities
 
-## 🐛 Troubleshooting
+```bash
+# Docker cleanup
+gitzone docker prune
 
-### Format Command Shows "Cancelled"
+# Open GitLab CI settings or pipelines for the current repo
+gitzone open ci
+gitzone open pipelines
 
-- Check your `npmextra.json` configuration
-- Try with `--yes --write` flags
-- Use `--verbose` for detailed output
+# Deprecate an old npm package interactively
+gitzone deprecate
 
-### Docker Commands Fail
+# Prepare a project for local work
+gitzone start
+
+# Generate a short unique ID
+gitzone helpers shortid
+```
+
+## Troubleshooting
 
-Ensure Docker daemon is running:
+Format only previews changes:
 
 ```bash
-docker info
+gitzone format --write
 ```
 
-### Services Won't Start
+Release says there is nothing to release:
 
 ```bash
-# Services auto-assign ports, but you can check the config
-cat .nogit/env.json
+# Make sure commits have populated the Pending changelog section
+gitzone commit
+```
 
-# Verify Docker is running
-docker ps
+Docker services fail to start:
 
-# Reassign ports if there are conflicts
+```bash
+docker info
+gitzone services status
 gitzone services reconfigure
 ```
 
-### Template Creation Issues
-
-Verify pnpm/npm is properly configured:
+Config looks outdated:
 
 ```bash
-npm config get registry
+gitzone config migrate 2
+gitzone config show --json
 ```
 
-### MongoDB Connection Issues
-
-- Ensure services are running: `gitzone services status`
-- Check firewall settings for the assigned ports
-- Use `gitzone services compass` for the correct connection string
-
-## 📈 Performance
-
-gitzone is optimized for speed:
-
-- ⚡ **Parallel processing** for format operations
-- 🧠 **Smart caching** to avoid redundant work
-- 📊 **Incremental updates** for meta repositories
-- 🐳 **Isolated services** prevent resource conflicts
-- 🎲 **Auto port assignment** eliminates manual configuration
-
 ## License and Legal Information
 
-This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./license) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.