Revive the Atomic Forge as a shadcn-style tool registry

.claude/.codebase-info/.map-state.json

@@ -1,8 +1,8 @@
 {
   "tool": "codebase-mapper",
-  "version": "2.8.0",
-  "mappedAt": "2026-07-18",
-  "gitCommit": "73dbc8be54f4ca32e71d28f5d9a7648dd9628c9b",
+  "version": "2.11.2",
+  "mappedAt": "2026-07-23",
+  "gitCommit": "8a90c1a87de30788e59fd28c606a4e2a2c9c89ed",
   "documents": [
     "architecture.md",
     "tech-landscape.md",
@@ -13,19 +13,21 @@
     "dependencies.md",
     "patterns.md",
     "coding-style.md",
-    "onboarding.md"
+    "onboarding.md",
+    "structure.md"
   ],
   "hashes": {
-    "INDEX.md": "17eaa0ba82f159465e126597aac349c6e4429330887b58742636734e15854313",
+    "INDEX.md": "6ca6422261a5a3fd84c714c2aeba11d54a7b9c62d1e0ccf4fb8d22dc42d2bddc",
     "architecture.md": "7c908f047e6b0f08824ccd7c3f674ad47bd547dde234d0bd424a6d2784c0cbb6",
     "tech-landscape.md": "cad1a11e5e63013a10cf07657d248196d0e3e4e14203eba7b777c1c123628198",
-    "directory-structure.md": "7e3fc4c3c8b89b6627beabcb6ddebd74b0ac7094e52718926fc87a94c932df84",
-    "entry-points.md": "6bd4ccae3d975196e03fc2c4e86007eba89f1f6427232fd8adce78ec97d6b432",
-    "modules.md": "1238c76664edb1c1667fda23f39507bcab5b760b57a3a3728d7104b2cf8032e7",
+    "directory-structure.md": "8ae4de1f8554a2cd074a9195b86107e75cdaa78c3b206e2a8d76ad3b78769b9c",
+    "entry-points.md": "a6dc81ecc5b3bfc67fa8f7c1dcc9f36d80b9be13bab4eb6a6eac238000f5e074",
+    "modules.md": "1bd4b75fb7af2d455aa2cc12ac9604c7766802158bcaf804e1c9819328f925bf",
     "communication.md": "49741a7455b0f162881e1cfb2d797dc8e3832cc8782796bbcb8a10529f2c5a0b",
     "dependencies.md": "b445a920c121e27006fec824add6865d01cf71212a517e5ff8b2058d3999037a",
-    "patterns.md": "12b96c2d4f8bc7507bcae39b2b385b9db4d0dec95ef6a2049958663aff021705",
+    "patterns.md": "9c6e46d129b45b3de7fedf9b581af3ecce074c95f1970b56ada1958ee6523f36",
     "coding-style.md": "2f939544333b927cf8731f5bb906ce03cb3a46afa50c9735011ff8f7e4caca9e",
-    "onboarding.md": "3d28c671dc095a2aadb297bd7ab200c677779a99c7534e03e55a3d64c935f07e"
+    "onboarding.md": "ccc30bd73115d603afa7dc1b39344174542f3142a7dde25182fb94fad3e63ded",
+    "structure.md": "a6d1f09a2b0f5aa3d68ec8f008244acf6cf032050670e9dcf76c8812ab8467b1"
   }
 }

.claude/.codebase-info/INDEX.md

@@ -1,10 +1,11 @@
 # Codebase Map — Atomic Agents
 
-*Last Updated: 2026-07-18*
+*Last Updated: 2026-07-23*
 
 Atomic Agents is a lightweight, modular Python framework for building agentic AI applications as
 composable, schema-driven building blocks (built on Instructor + Pydantic). This repository is a
-`uv`-workspace **monorepo**: the core framework, a TUI tool installer, a tool library, and examples.
+`uv`-workspace **monorepo**: the core framework, a Forge CLI client, a vendored-code tool registry, and
+examples.
 
 **Stack:** Python ≥3.12 · Instructor · Pydantic v2 · LiteLLM · MCP · Textual · uv + Hatchling
 **Shape:** Monorepo — `atomic-agents/` (core lib) · `atomic-assembler/` (CLI) · `atomic-forge/` (tools) · `atomic-examples/` (examples)
@@ -24,6 +25,7 @@ composable, schema-driven building blocks (built on Instructor + Pydantic). This
 | [patterns.md](./patterns.md) | Atomicity, schema-driven I/O, context providers, testing |
 | [coding-style.md](./coding-style.md) | Formatting, linting, naming conventions |
 | [onboarding.md](./onboarding.md) | Setup with uv, tests, docs, common tasks |
+| [structure.md](./structure.md) | Layout intent: where new code goes, non-obvious conventions |
 
 ## How to use this map
 

.claude/.codebase-info/directory-structure.md

@@ -1,6 +1,6 @@
 # Directory Structure
 
-*Last Updated: 2026-07-18*
+*Last Updated: 2026-07-23*
 
 ## Root Layout
 
@@ -14,11 +14,14 @@ atomic-agents/                  # repo root (uv workspace)
 │       ├── connectors/mcp/     #     Model Context Protocol integration
 │       └── utils/              #     token counter, tool-message formatting
 │   └── tests/                  #   pytest suite (agents/, base/, context/, connectors/, utils/)
-├── atomic-assembler/           # Textual TUI (`atomic` command) to install forge tools
-│   └── atomic_assembler/       #   main.py, app.py, screens/, widgets/, utils.py, constants.py
-├── atomic-forge/               # library of standalone tools (NOT a package)
-│   ├── tools/<tool>/           #   one folder per tool: tool/<tool>.py, tests/, pyproject.toml
-│   └── guides/                 #   tool authoring guides (e.g. tool_structure.md)
+├── atomic-assembler/           # Textual TUI + noninteractive `atomic` Forge client
+│   └── atomic_assembler/       #   main.py, source/index/download utilities, TUI screens/widgets
+├── atomic-forge/               # vendored-code tool registry (NOT a package)
+│   ├── tools/<tool>/           #   standalone package: tool/, tests/, pyproject.toml, requirements.txt
+│   ├── conformance/            #   registry package-contract test suite
+│   ├── scripts/                #   deterministic index generator
+│   ├── index.json              #   generated tool catalog
+│   └── guides/                 #   tool authoring guides
 ├── atomic-examples/            # 16 runnable example apps (each its own project)
 ├── claude-plugin/atomic-agents/ # AI-assistant plugin: 7 skills + 2 subagents (Claude Code plugin,
 │                               #   also installable cross-tool via `npx skills add eigenwise/atomic-agents`)
@@ -42,15 +45,16 @@ prompts and stores conversation history. `connectors/mcp/` bridges to MCP server
 token accounting via LiteLLM.
 
 ### `atomic-assembler/atomic_assembler/`
-A Textual terminal UI launched by the `atomic` command (`main.py:main`). `app.py` routes between
-`screens/` (main menu, tool explorer, file picker, README viewer); `utils.py` clones the GitHub repo
-and copies a selected tool into the user's project.
-
-### `atomic-forge/tools/`
-13 self-contained tools (`arxiv_search`, `calculator`, `tavily_search`, `weather`,
-`webpage_scraper`, `wikipedia_search`, …). Each tool folder contains `tool/<name>.py` (Input/Output
-`BaseIOSchema` + a `BaseToolConfig` + a `BaseTool` subclass), `tests/`, and its own
-`pyproject.toml`/`requirements.txt`. Tools are copied into user projects, not pip-installed.
+The `atomic` entry point runs the Textual UI with no subcommand and supports scripting with `list`,
+`download`, and `sources` subcommands. Source utilities clone configured Git repositories, resolve an
+indexed package only inside the configured tools directory, and copy the full standalone package into the
+user’s project. Source/index metadata is treated as untrusted before it reaches the terminal or filesystem.
+
+### `atomic-forge/`
+A shadcn-style collection of 13 self-contained tool packages. Each package contains `tool/<name>.py`
+(Input/Output `BaseIOSchema`, `BaseToolConfig`, `BaseTool`), tests, `pyproject.toml`, and
+`requirements.txt`; those files stay with the package when it is downloaded. `index.json` is generated
+from each package’s metadata, and `conformance/` plus CI enforce the registry contract.
 
 ### `atomic-examples/`
 16 standalone example apps (`quickstart`, `rag-chatbot`, `deep-research`, `web-search-agent`,

.claude/.codebase-info/entry-points.md

@@ -1,6 +1,6 @@
 # Entry Points
 
-*Last Updated: 2026-07-05*
+*Last Updated: 2026-07-23*
 
 ## 1. Library API (the primary entry point)
 
@@ -23,7 +23,12 @@ result = agent.run(BasicChatInputSchema(chat_message="Hello"))
 
 | Entry | Type | Purpose | File |
 |-------|------|---------|------|
-| `atomic` | Textual TUI | Browse & install forge tools into a project | `atomic-assembler/atomic_assembler/main.py:main` |
+| `atomic` | Textual TUI + command-line interface | Browse and install vendored Forge tools | `atomic-assembler/atomic_assembler/main.py:main` |
+
+The noninteractive surface is `atomic list`, `atomic download <name> [--dest DIR]`, and
+`atomic sources list|add|remove`. Sources are Git repositories, including private ones accessed through
+normal Git SSH or credential-helper setup. A qualified name such as `company/weather` resolves a collision
+between source catalogs. The TUI remains available when no subcommand is supplied.
 
 Declared in `pyproject.toml` (`[project.scripts]  atomic = "atomic_assembler.main:main"`). Flags:
 `--enable-logging`, `--version`.

.claude/.codebase-info/modules.md

@@ -1,6 +1,6 @@
 # Key Modules
 
-*Last Updated: 2026-07-05*
+*Last Updated: 2026-07-23*
 
 ## Core framework — `atomic-agents/atomic_agents/`
 
@@ -46,18 +46,20 @@
 
 ### atomic-assembler (CLI)
 - **Location:** `atomic-assembler/atomic_assembler/`
-- **Purpose:** Textual TUI to browse and install forge tools into a user project.
-- **Key files:** `main.py` (`main()`; argparse `--enable-logging`, `--version`), `app.py`
-  (`AtomicAssembler(App)`), `screens/` (`main_menu`, `atomic_tool_explorer`, `file_explorer`,
-  `tool_info_screen`), `widgets/`, `utils.py` (`GithubRepoCloner`, `AtomicToolManager`),
-  `constants.py` (GitHub URL, `TOOLS_SUBFOLDER`).
+- **Purpose:** Textual TUI plus the `atomic` command-line client for vendoring Forge tool packages.
+- **Key files:** `main.py` (argparse commands and TUI entry), `app.py` (`AtomicAssembler(App)`),
+  `screens/`, `widgets/`, `utils.py` (source clone/index resolution/download), `constants.py`
+  (`ForgeSource`, source validation and display safety).
+- **Source model:** configured sources live in `~/.atomic-assembler/sources.json`; each source names a
+  Git URL, branch, and tools directory. Git authentication stays with SSH or the user’s credential helper.
 
 ### atomic-forge (tools)
-- **Location:** `atomic-forge/tools/`
-- **Purpose:** 13 standalone tools, each an independent mini-project following the `BaseTool` pattern,
-  copied into user projects by the assembler (build files such as `pyproject.toml` / `requirements.txt`
-  / `uv.lock` are skipped on copy).
-- **Authoring guide:** `atomic-forge/guides/tool_structure.md`.
+- **Location:** `atomic-forge/`
+- **Purpose:** a vendored-code registry of 13 standalone tools. `index.json` is generated from package
+  metadata by `scripts/generate_index.py`; `conformance/` verifies package structure and metadata.
+  CI requires a fresh index and runs every tool’s test suite.
+- **Authoring guide:** `atomic-forge/guides/tool_structure.md`; user-facing workflow:
+  `docs/guides/atomic_forge.md`.
 
 ### atomic-examples
 - **Location:** `atomic-examples/`

.claude/.codebase-info/onboarding.md

@@ -1,6 +1,6 @@
 # Onboarding
 
-*Last Updated: 2026-06-13*
+*Last Updated: 2026-07-23*
 
 ## Prerequisites
 - Python **≥3.12**
@@ -22,6 +22,8 @@ it. To launch the tool-installer TUI: `uv run atomic` (or `atomic` once it's on
 |---------|---------|
 | `uv sync` | Install/update all workspace dependencies |
 | `uv run pytest --cov=atomic_agents atomic-agents` | Run the core test suite with coverage |
+| `uv run pytest atomic-assembler` | Run Atomic Assembler CLI and source-handling tests |
+| `uv run pytest atomic-forge/conformance` | Verify Forge package and registry contract |
 | `uv run black --check atomic-agents atomic-assembler atomic-examples atomic-forge` | Format check |
 | `uv run flake8 --extend-exclude=.venv atomic-agents atomic-assembler atomic-examples atomic-forge` | Lint |
 | `cd docs && uv run make html` | Build the Sphinx docs |
@@ -30,9 +32,12 @@ it. To launch the tool-installer TUI: `uv run atomic` (or `atomic` once it's on
 ## Common tasks
 - **Build a new agent:** define input/output `BaseIOSchema` subclasses, wrap an LLM client with
   Instructor, pass it to `AtomicAgent[In, Out](AgentConfig(...))`. See `patterns.md` + `entry-points.md`.
+- **Use a Forge tool:** run `atomic list`, then `atomic download <name>` (or
+  `atomic download <source>/<name>` for a collision). Add private Git registries with
+  `atomic sources add <name> <url> --tools-path tools`.
 - **Add a forge tool:** create `atomic-forge/tools/<name>/` following
-  `atomic-forge/guides/tool_structure.md` (input/output schemas, `BaseToolConfig`, a `BaseTool`
-  subclass, `tests/`).
+  `atomic-forge/guides/tool_structure.md`, give it tests and dependency metadata, regenerate
+  `atomic-forge/index.json`, then run the conformance suite.
 - **Add an example:** create `atomic-examples/<name>/` with its own `pyproject.toml`.
 - **Release:** `build_and_deploy.ps1 <major|minor|patch>` (needs `PYPI_TOKEN`).
 

.claude/.codebase-info/patterns.md

@@ -1,6 +1,6 @@
 # Patterns & Conventions
 
-*Last Updated: 2026-07-05*
+*Last Updated: 2026-07-23*
 
 ## Atomicity
 Build with small, single-purpose, composable parts ("LEGO blocks"): each agent, tool, and context
@@ -21,8 +21,11 @@ the next's input. See `atomic-examples/deep-research` and `orchestration-agent`.
 ## Tools
 - A tool is a `BaseTool[InputSchema, OutputSchema]` with a `run(params) -> OutputSchema` method and an
   optional `BaseToolConfig` (override `title`/`description` to disambiguate similar tools).
-- Forge tool layout (`atomic-forge/guides/tool_structure.md`): imports → input schema → output
-  schema(s) → config → tool class + logic → example usage.
+- A Forge tool is a complete, vendorable package: source, tests, README, `pyproject.toml`, and
+  `requirements.txt`. Downloaded tools are owned by the receiving project, never installed as hidden
+  framework runtime behavior.
+- Forge package layout and conformance: `atomic-forge/guides/tool_structure.md` and
+  `atomic-forge/conformance/`. Check the Forge catalog before generating a tool from scratch.
 
 ## Memory
 - `BaseChatHistory` (`context/base_chat_history.py`) is an interface-only ABC declaring the memory

.claude/.codebase-info/structure.md

@@ -0,0 +1,31 @@
+# Project structure
+
+*Last Updated: 2026-07-23*
+
+Light notes on intent only — the actual tree is in [directory-structure.md](./directory-structure.md).
+
+## What this project is
+The Atomic Agents monorepo: a Python framework for building agentic AI apps as schema-driven,
+composable components, published on PyPI as `atomic-agents`, plus its CLI, tool library, examples,
+and the Claude Code plugin distributed from this repo.
+
+## Organizing principle
+uv-workspace monorepo whose **root is the published package**. Everything else (assembler, forge
+tools, examples) is a workspace member that depends on the core but never the reverse.
+
+## Where things go
+| Kind of thing | Lives in | Notes |
+|---------------|----------|-------|
+| Framework code | `atomic-agents/atomic_agents/` | the only code that ships to PyPI |
+| New forge tool | `atomic-forge/tools/<name>/` | follow `atomic-forge/guides/tool_structure.md`; NOT bundled with the package |
+| New example | `atomic-examples/<name>/` | self-contained project with its own `pyproject.toml` |
+| Claude Code plugin | `claude-plugin/` (+ `.claude-plugin/` manifest) | versioned separately from the PyPI package |
+| Docs | `docs/` | Sphinx + MyST |
+
+## Conventions that aren't obvious from the tree
+- Tools are deliberately downloadable, not importable: never add a forge tool as a core dependency.
+- The package version lives in the root `pyproject.toml`; `__version__` reads installed metadata,
+  don't hardcode it anywhere.
+- Every `BaseIOSchema` subclass needs a non-empty docstring — enforced at class-definition time,
+  and it flows into the LLM prompt.
+- Releases go through `build_and_deploy.ps1` (see the `release` skill), not manual builds.

.github/workflows/code-quality.yml

@@ -40,6 +40,11 @@ jobs:
           uv sync
           uv run pip list  # Verify installation
 
+      - name: Verify Forge Index
+        run: |
+          uv run python atomic-forge/scripts/generate_index.py
+          git diff --exit-code -- atomic-forge/index.json
+
       - name: Verify Black Installation
         run: |
           uv run which black || echo "Black not found"
@@ -57,3 +62,34 @@ jobs:
       - name: Run Tests
         run: uv run pytest --cov=atomic_agents atomic-agents
         if: success()
+
+  forge-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Install Forge test dependencies
+        run: uv sync --all-packages
+
+      - name: Run Forge conformance suite
+        run: uv run pytest atomic-forge/conformance
+
+      - name: Run every Forge test suite
+        run: |
+          for tool in atomic-forge/tools/*; do
+            if [ ! -d "$tool/tests" ]; then
+              echo "Missing test directory: $tool/tests"
+              exit 1
+            fi
+            uv run --project "$tool" pytest "$tool/tests"
+          done

AGENTS.md

@@ -393,6 +393,8 @@ This project captures repeatable agent workflows as small, single-purpose,
 verified skills under `.claude/skills/`. Build and maintain them with the
 **skill-forge** skill — never do a repeatable workflow ad hoc.
 
+Before writing a tool from scratch, check the Forge for an existing one.
+
 **Proactively (notice → propose → ask):** while working, if you notice a
 multi-step workflow being repeated with no skill, a SKILL.md growing past ~500
 lines or sprouting a second capability, a skill whose instructions have drifted