release: v0.3.0 apoc — clone/purge commands, docs, branding, README redesign

- Rename connect/disconnect to clone/purge
- Complete documentation suite (specs, features, ADRs, glossary)
- Matrix/Agent Smith visual identity
- README with banner, badges, architecture, command reference
- 67 tests passing, lint clean

Author: nullhack

CHANGELOG.md

@@ -1,10 +1,20 @@
 # Changelog
 
-> *Connect AI agent configurations to any project.*
+> *Clone AI agent configurations into any project.*
 
 All notable changes to agents-smith will be documented in this file.
 
-## [2.0.0] - 20260502
+## [0.3.0] - assimilated Apoc - 20260502
+
+### Changed
+
+- **Breaking:** `smith connect` renamed to `smith clone` — the command that fetches template files and writes them to a project
+- **Breaking:** `smith disconnect` renamed to `smith purge` — the command that removes smith-managed files
+- Complete documentation rewrite: specs, features, ADRs, glossary, domain model, technical design, context map
+- Matrix/Agent Smith visual identity: green phosphor palette, S scan-line lettermark, dark void backgrounds
+- README redesigned with banner, badges, architecture diagram, and command reference
+
+## [0.2.0] - 20260501
 
 ### Added
 

README.md

@@ -1,46 +1,76 @@
-# agents-smith
+<div align="center">
+  <img src="docs/assets/banner.svg" alt="smith — Clone AI agent configurations into any project" width="800">
+</div>
 
-Clone AI agent configurations (AGENTS.md, .opencode/, .flowr/, .templates/) to any project.
+<br>
+
+<p align="center">
+  <strong>Clone AI agent configurations into any project.</strong><br>
+  <code>smith clone</code> fetches AGENTS.md, .opencode/, .flowr/, .templates/ from any source.<br>
+  <code>smith purge</code> removes them cleanly. No leftovers.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/agents-smith/"><img src="https://img.shields.io/pypi/v/agents-smith?color=%2300FF41&label=pypi&style=flat-square" alt="PyPI"></a>
+  <a href="https://github.com/nullhack/agents-smith/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-%2300FF41?style=flat-square" alt="License"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-%E2%89%A513.0-%2300FF41?style=flat-square" alt="Python"></a>
+</p>
+
+---
 
 ## Install
 
 ```bash
 pip install agents-smith
 ```
 
-## Usage
+## Quick start
 
 ```bash
-# Clone — downloads templates from the default source (temple8)
+# Clone the default template (temple8) into your project
 smith clone
 
-# Clone from a specific source
-smith clone --source github:myorg/my-template
-smith clone --source /path/to/local/template
-smith clone --source https://example.com/template.zip
-
-# Clone and overwrite existing files
-smith clone --overwrite
-
-# Purge — removes files listed in the smith-managed .gitignore section
+# Purge all smith-managed files when you're done
 smith purge
 ```
 
+That's it. AGENTS.md, .opencode/, .flowr/, and .templates/ appear in your project, tracked in .gitignore. When you're done, `smith purge` removes every file and directory — no orphan files, no stale .gitignore entries.
+
 ## Source resolution
 
-1. `--source` CLI flag (highest priority)
-2. `[tool.smith] source = "..."` in pyproject.toml
-3. Default: `github:nullhack/temple8`
+| Priority | Source | Example |
+|----------|--------|---------|
+| 1 — CLI flag | `--source` | `smith clone --source github:myorg/templates` |
+| 2 — Config | `[tool.smith] source` in pyproject.toml | `source = "github:myorg/templates"` |
+| 3 — Default | `github:nullhack/temple8` | Used when no flag or config is set |
 
-## How it works
+## Commands
 
-**clone**: Downloads AGENTS.md, .opencode/, .flowr/, .templates/ from the source. Skips any file or directory that already exists unless `--overwrite` is set. Adds a `# smith managed` section to .gitignore listing what was written.
+### `smith clone`
 
-**purge**: Reads the smith-managed section in .gitignore and deletes every file/directory listed there. Does not remove the .gitignore section itself.
+Fetches template files from a source, filters them by allowed topics, writes them to the project directory, and adds a managed section to .gitignore.
 
-## .gitignore section
+```bash
+smith clone                                    # default source
+smith clone --source github:myorg/templates    # GitHub shorthand
+smith clone --source /path/to/local/template   # local directory
+smith clone --source https://example.com/t.zip # URL to archive
+smith clone --overwrite                        # replace existing files
+```
+
+**Safety:** Only files matching allowed topics (AGENTS.md, .opencode/, .flowr/, .templates/) are ever written. Existing files and directories are skipped unless `--overwrite` is passed.
+
+### `smith purge`
+
+Reads the smith-managed section in .gitignore and deletes every file and directory listed there. The .gitignore section itself is preserved so you can clone again later.
 
+```bash
+smith purge    # removes all smith-managed files
 ```
+
+## .gitignore section
+
+```gitignore
 # smith managed
 AGENTS.md
 .opencode/
@@ -49,4 +79,19 @@ AGENTS.md
 # end smith managed
 ```
 
-Only items listed in this section are deleted on purge. Edit this section to control what smith manages.
+Only items in this section are removed on purge. Edit it to control what smith manages.
+
+## Architecture
+
+```
+smith/
+├── cli.py         # CLI — argparse, subcommands (clone, purge)
+├── core.py        # Domain — resolve_source, fetch, clone, purge, FileSpec
+└── gitignore.py   # Infrastructure — .gitignore section management
+```
+
+Flat module structure. Two commands. No framework overhead. The allowed-topics list is a compile-time safety boundary — only agentic configuration files are ever written to your project, regardless of what the source archive contains.
+
+## License
+
+MIT

docs/branding/branding.md

@@ -11,7 +11,7 @@ Agents read this file before generating release names, C4 diagrams, README banne
 ## Identity
 
 - **Project name:** agents-smith
-- **Tagline:** Connect AI agent configurations to any project
+- **Tagline:** Clone AI agent configurations into any project
 - **Mission:** Eliminate the repetitive, error-prone process of manually copying AI agent configuration files into projects by providing a single command to fetch, install, and track them — then cleanly purge when done.
 - **Vision:** Every developer can add or remove agentic tooling from any project with one command, confident that nothing is left behind or accidentally overwritten. Like Agent Smith in the Matrix, smith enters a project, copies its patterns, and returns something more capable than what it found.
 - **Tone of voice:** direct, precise, minimal
@@ -40,9 +40,35 @@ Dark void background (`#0F1117`) with the S logo mark scaled to height, followed
 
 ## Release Naming
 
-- **Convention:** `matrix-character` (adjective-matrix-character)
-- **Theme:** The Matrix — each release is named after a character, concept, or quote from the Matrix franchise
-- **Excluded words:** easy, simple, just, quick, scaffold, boilerplate
+- **Convention:** `adjective-character` — one adjective from the approved list below, paired with a Matrix character name
+- **Rule:** No adjective-character pair may be reused across releases
+- **Examples:** assimilated Apoc, cloned Oracle, overwritten Bane
+
+### Approved adjectives
+
+These adjectives reference Agent Smith's core abilities: assimilation, replication, and overwriting.
+
+| Adjective | Meaning |
+|-----------|---------|
+| assimilated | Absorbed into the collective — Agent Smith's signature ability |
+| cloned | Directly replicated, like Smith copies himself |
+| replicated | Exact copy produced, like Smith spawning duplicates |
+| infected | Overwritten from within, like Smith corrupts programs |
+| overwritten | Identity replaced, like Smith overwrites Bane |
+| copied | Duplicated pattern transferred to a new host |
+| inserted | Injected into a system, like Smith inserts himself |
+| spawned | Multiple instances emerged from one source |
+| duplicated | Mirror image created from the original |
+| imprinted | Pattern transferred and stamped onto a host |
+| propagated | Spread through the system to new targets |
+| manifested | Brought into existence from the pattern |
+| incorporated | Absorbed into the larger collective |
+| exfiltrated | Extracted from one system and redeployed elsewhere |
+| grafted | Spliced onto an existing structure |
+
+### Matrix character pool
+
+Apoc, Bane, Cypher, Dozer, Link, Mouse, Niobe, Oracle, Seraph, Switch, Tank, Trinity, Morpheus, Neo
 
 ## Wording
 

pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agents-smith"
-version = "2.0.0"
-description = "Connect AI agent configurations to any project"
+version = "0.3.0"
+description = "Clone AI agent configurations into any project"
 readme = "README.md"
 requires-python = ">=3.13"
 license = { file = "LICENSE" }

smith/__init__.py

@@ -1 +1 @@
-__version__ = "2.0.0"
+__version__ = "0.3.0"