artoo-artifacts 0.1.0__tar.gz

artoo_artifacts-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync
+      - run: uv run ruff check src tests --output-format=github
+      - run: uv run pytest -q

artoo_artifacts-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+# Publishes artoo to PyPI via trusted publishing (OIDC — no stored tokens).
+#
+# PREREQUISITE (one-time): register a pending publisher on PyPI →
+# Account settings → Publishing, with project "artoo-artifacts", owner
+# "lavallee", repo "artoo", workflow "publish.yml", environment
+# "pypi-artoo-artifacts". The GitHub environment is created
+# automatically on first workflow run.
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi-artoo-artifacts
+      url: https://pypi.org/p/artoo-artifacts
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # Idempotent re-runs: a version already on PyPI is skipped, not an
+          # error — needed when a partial publish is completed by re-dispatch.
+          skip-existing: true

artoo_artifacts-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# python
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# artoo local state (never committed)
+.artoo/targets.toml
+
+# editors / os
+.DS_Store
+.idea/
+.vscode/

artoo_artifacts-0.1.0/.somm/service_token

@@ -0,0 +1 @@
+VTocK3HQdI6c9erJZyS_-LZwCyGZJtCdvZ8pOgxGY1s

artoo_artifacts-0.1.0/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to artoo are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — 2026-07-10
+
+Published on PyPI as **`artoo-artifacts`** — the bare `artoo` name is
+blocked by a confusable-name collision with the abandoned `ar_too`
+project. The import package and the command are `artoo` either way.
+
+First public release. Proven end-to-end on day one: the explainer
+generator ran against the public [somm](https://github.com/lavallee/somm)
+repo (55k LOC → 15 analysis briefs → 6 pages) and published to GitHub
+Pages through the github-pages adapter.
+
+### Added
+
+- Artifact model: `artifact.toml` manifest, `site/` publishable root,
+  research backing behind a deny-by-default deploy firewall.
+- CLI: `init`, `list`, `status`, `build`, `deploy`, `lib`, `generate`,
+  `doctor`.
+- Deploy adapters: `github-pages` (legacy `/docs`, workflow, and branch
+  modes), `rsync` (named targets, secrets outside the repo), `command`.
+- Site libraries: vendored-with-provenance model; built-in `artoo-kit`
+  (tokens, base, article layout, components).
+- Plugin system: `artoo.generators`, `artoo.deployers`, `artoo.libraries`
+  entry-point groups.
+- Workers: tiered delegation to local agent CLIs (`codex` for analysis
+  fan-out, `claude` for synthesis); no API keys in core.
+- `explainer` generator: multi-page repo explainer with deterministic
+  inventory, per-module analysis, narrative synthesis, Mermaid diagrams,
+  and a build colophon.
+- Optional flip integration (`artoo[research]`): generator runs recorded
+  as reporter's-notebook sources, claims, and sessions.

artoo_artifacts-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing to artoo
+
+Thanks for helping. Ground rules that keep artoo coherent:
+
+## Setup
+
+```bash
+git clone https://github.com/lavallee/artoo && cd artoo
+uv sync
+uv run pytest -q
+```
+
+## Principles
+
+- **Core stays light.** `pip install artoo` must work with one small
+  dependency (`click`). Heavy or network-bound features go behind extras
+  or plugins. Model SDKs never enter core — generators shell out to agent
+  CLIs the user already has.
+- **The firewall is sacred.** Nothing outside an artifact's `site/` root
+  ships, ever. Notebook files and `_`/`.`-prefixed paths never ship even
+  inside `site/`. Any change touching deploy paths needs tests proving
+  the firewall holds.
+- **Manifests must diff cleanly.** `artifact.toml` is written with stable
+  key order, scalars before tables. Don't introduce nondeterminism.
+- **Adapters degrade loudly.** When a deployer or worker can't proceed
+  (missing CLI, ambiguous Pages config), it says exactly what it found
+  and what to do — it never guesses silently.
+- **Ecosystem over monolith.** New generators, deployers, and site
+  libraries belong in their own repos using the entry-point groups.
+  Reference implementations live here only when they're load-bearing for
+  the core experience.
+
+## Tests
+
+One `test_<module>.py` per source module, `tmp_path`-based, no network,
+no global state. CI runs `ruff check` + `pytest` on Python 3.12 and 3.13.

artoo_artifacts-0.1.0/DESIGN.md

@@ -0,0 +1,249 @@
+# artoo — design
+
+artoo generates and manages **artifacts**: self-contained, publishable HTML
+bundles (mini-sites) that pair presentation with the research that backs it.
+It is the tool layer for a growing practice: getting explanations of systems
+out of LLMs as real pages — with navigation, diagrams, and provenance —
+instead of markdown dumps, and composing reports from multiple assets.
+
+This document records the v0.1 architecture and the reasoning behind it.
+
+## Lineage
+
+artoo generalizes patterns proven in weaver, a private static-site research
+workbench by the same author, and adopts the packaging
+conventions of its public siblings [vizier](https://github.com/lavallee/vizier),
+[somm](https://github.com/lavallee/somm), and
+[flip](https://github.com/lavallee/flip). The load-bearing ideas imported:
+
+- **Descriptor as source of truth.** Every artifact carries a small TOML
+  manifest; everything else (listings, graphs, deploy routing) is derived
+  from it, never hand-maintained.
+- **The private-file firewall.** Research notes, notebooks, and anything
+  `_`- or `.`-prefixed sit *next to* the presentation but never publish.
+  Evidence lives with the piece; the deploy path is deny-by-default.
+- **Named deploy targets, per-artifact routing.** The mechanism (rsync/ssh,
+  Pages, command) is generic; the values (hosts, users, paths) are local
+  config that never enters the repo.
+- **Kind-aware scaffolding.** New artifacts start from an archetype
+  (explainer, report, reference guide, …) with an appropriate skeleton and
+  a research notebook stamped in.
+- **Revision snapshots.** Publishing is preceded by cheap local snapshots
+  so any shipped state can be diffed and recovered.
+
+Where artoo deliberately departs from its ancestor:
+
+- **Artifacts live anywhere.** The ancestor housed all projects in one
+  repo under `projects/`. artoo artifacts live inside whatever repo owns
+  them — a library's explainer lives in that library's repo — and one repo
+  can hold many artifacts. artoo is installed once and invoked anywhere.
+- **No bundler.** Artifacts are self-contained static sites: vendored
+  assets, system font stacks, no build-time JS toolchain. What you commit
+  is what ships. (A manifest may declare build *commands* — e.g. "export
+  this dataset to JSON" — but artoo itself never requires Node or a
+  bundling step.)
+- **No direct model calls in core.** Like its ancestor, artoo core is a
+  renderer/manager. Generators delegate model work to *worker CLIs* the
+  user already has (`claude`, `codex`), selected per task tier. artoo
+  never holds API keys.
+
+## Concepts
+
+### Artifact
+
+An artifact is a directory marked by an `artifact.toml`. Canonical shape:
+
+```
+my-explainer/
+  artifact.toml     # the manifest (source of truth)
+  site/             # the publishable mini-site — self-contained
+    index.html
+    style.css
+    lib/            # vendored site libraries (managed, see below)
+  notebook/         # research backing (flip notebook) — never deployed
+  work/             # generator working files — never deployed
+```
+
+`site/` is committed. It must render from a file:// URL or any static
+host — no external requests required (CDN references are allowed only in
+`vendor`-recorded fallbacks). Everything outside `site/` is backing
+material and never leaves the repo.
+
+### Manifest (`artifact.toml`)
+
+```toml
+[artifact]
+slug = "chart-forms"
+title = "Chart forms — when, how, and when not"
+description = "A guide to 43 chart-form patterns."
+kind = "reference-guide"      # explainer | report | reference-guide | ...
+status = "live"               # draft | building | live | archived
+created = "2026-07-10"
+
+[build]
+# Optional commands that refresh generated inputs before deploy.
+commands = ["vizier patterns export -o site/data.json"]
+site = "site"                 # publishable root, relative to the manifest
+
+[research]
+notebook = "notebook"         # optional flip notebook directory
+
+[deploy]
+target = "github-pages"
+
+[deploy.github-pages]
+# artoo inspects the repo's actual Pages configuration and routes
+# accordingly: legacy /docs serving, an Actions workflow, or a branch.
+subpath = "reader"            # where under the published site this lands
+
+[[libraries]]
+name = "artoo-kit"
+version = "0.1.0"
+sha256 = "…"                  # provenance of the vendored copy
+
+[[vendor]]
+name = "mermaid"
+url = "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"
+sha256 = "…"
+path = "site/lib/vendor/mermaid.min.js"
+```
+
+Top-level tables only, scalars before tables, stable key order on write —
+manifests must diff cleanly in git.
+
+### Site libraries
+
+The tension: artifacts should be **self-contained and stable** (they keep
+working when the tooling moves on) yet **easy to upgrade**. Resolution:
+libraries are *vendored with provenance*. `artoo lib add artoo-kit` copies
+the library's files into `site/lib/artoo-kit/` and records
+name/version/hash in the manifest. `artoo lib status` detects drift (local
+edits vs. upstream); `artoo lib update` re-vendors a newer version.
+
+- artoo ships one built-in library, **artoo-kit**: design tokens
+  (dark-default + light theme), base styles, article/prose layout with
+  margin notes and pull quotes, components (nav, cards, callouts, tables,
+  badges), and small JS helpers. Neutral, system fonts, ~tens of KB.
+- External libraries live in **their own repos/packages** and register via
+  the `artoo.libraries` entry point, or are vendored from a URL with a
+  pinned hash (`[[vendor]]`). Core artoo stays small; the ecosystem grows
+  outside it.
+
+### Deployment
+
+Adapters, discovered via the `artoo.deployers` entry point group:
+
+- **`github-pages`** — deployment intelligence lives here. It reads the
+  repo's actual Pages state (`gh api repos/{owner}/{repo}/pages`) and
+  handles the three real-world modes: *legacy* serving from `/docs` or
+  root (copy the built site into place, commit), *workflow*
+  (generate/maintain an `actions/deploy-pages` workflow that assembles
+  artifacts), or *branch* (push to `gh-pages`). It refuses to guess when
+  the config is ambiguous and says exactly what it found.
+- **`rsync`** — ssh/rsync to named targets. Targets (host/user/path/key)
+  live in `~/.config/artoo/targets.toml` or a git-ignored
+  `.artoo/targets.toml` at the repo root — never in the manifest.
+- **`command`** — an arbitrary publish command run with `ARTOO_SITE_DIR`,
+  `ARTOO_SLUG`, etc. in the environment. The escape hatch that makes any
+  bespoke pipeline work today.
+- Future adapters (vercel, cloudflare) are plugins; nothing in core
+  assumes a particular host.
+
+`artoo deploy` always runs the firewall check first: notebook files,
+`_`/`.`-prefixed paths, and anything outside `site/` cannot ship.
+
+### Plugins
+
+Three entry-point groups, all Python:
+
+| group              | provides                          | example            |
+|--------------------|-----------------------------------|--------------------|
+| `artoo.generators` | `artoo generate <name> …`         | `explainer`        |
+| `artoo.deployers`  | `[deploy] target = <name>`        | `github-pages`     |
+| `artoo.libraries`  | vendorable asset bundles          | `artoo-kit`        |
+
+Core ships reference implementations of each; everything else lives in
+separate repos. A generator is a callable that receives a context (target
+artifact, repo root, worker pool, options) and produces/updates the
+artifact.
+
+### Workers and model tiers
+
+Generators do model work through **workers** — thin shell-outs to agent
+CLIs already on the machine and already authenticated:
+
+```toml
+[workers]                      # optional overrides in artifact.toml
+analysis  = "codex"            # fan-out, high-volume, cheap
+synthesis = "claude"           # narrative, structure, judgment
+```
+
+- `codex` → `codex exec --sandbox read-only …` (bulk per-module analysis)
+- `claude` → `claude -p … --model <tier>` (synthesis, editing, review)
+
+Workers return text/JSON; generators validate and record results. If a
+worker CLI is missing, the generator degrades explicitly (skips the stage
+and says so) rather than failing the whole run. No API keys, no vendored
+SDKs, no phone-home.
+
+### Research backing
+
+If [flip](https://github.com/lavallee/flip) is installed alongside artoo,
+generators record what they learned as a flip reporter's notebook inside
+the artifact: analyzed files become graded sources, generated statements
+become claims with `file:line` provenance, and each run is a session. The
+site is then a *render* of the notebook in flip's sense. Without flip,
+generators fall back to plain markdown notes in `work/`. Either way the
+material stays behind the firewall.
+
+## The explainer generator
+
+The first serious generator: `artoo generate explainer --repo <path>`
+builds a detailed multi-page explainer of a code repository.
+
+Pipeline (each stage resumable, artifacts cached in `work/`):
+
+1. **Inventory** (deterministic, no models) — file tree, LOC, language
+   split, package/workspace layout, entry points, dependency graph
+   between modules, git history shape, test topology, existing docs.
+2. **Analysis fan-out** (analysis tier) — per-module briefs: what it does,
+   key types/functions, invariants, dependencies, surprises. Structured
+   output, validated, recorded as notebook sources/claims.
+3. **Synthesis** (synthesis tier) — the narrative: what this system is,
+   the architecture story, data flow, design decisions worth telling,
+   reading paths for different audiences. Produces page plans, then pages.
+4. **Diagrams** — architecture/data-flow diagrams emitted as Mermaid
+   source, rendered client-side by a vendored `mermaid.min.js`.
+5. **Assembly** — pages composed with artoo-kit into `site/`: overview,
+   architecture, module reference, data model, operations/how-to-read
+   pages, with cross-links and a nav manifest.
+
+The generated site carries a colophon: which tiers ran, when, against
+which commit — an explainer is a *dated snapshot*, and says so.
+
+## CLI surface (v0.1)
+
+```
+artoo init [path] --kind <kind> --title <t>   scaffold an artifact
+artoo list [root]                             discover artifacts under a tree
+artoo status [artifact]                       manifest, firewall, lib drift
+artoo build [artifact]                        run build commands + checks
+artoo deploy [artifact] [--dry-run]           firewall check, then adapter
+artoo lib add|update|status|list              manage vendored libraries
+artoo generate <generator> [opts]             run a generator plugin
+artoo doctor [root]                           repo-wide coherence report
+```
+
+## Non-goals (v0.1)
+
+- No hosted service, no accounts, no telemetry.
+- No WYSIWYG editing; artifacts are files in git.
+- No bundler integration; if a project needs one, its build commands can
+  call it, but artoo won't manage it.
+- No model API clients in core, ever.
+
+## Success criterion for v0.1
+
+Run the explainer against the public somm repo, land the artifact in
+somm's `site/` folder, and publish it through the github-pages adapter
+without disturbing somm's existing landing page.

artoo_artifacts-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marc Lavallee
+
+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.

artoo_artifacts-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: artoo-artifacts
+Version: 0.1.0
+Summary: Generate and manage artifacts: self-contained HTML mini-sites that pair presentation with the research backing it.
+Project-URL: Homepage, https://github.com/lavallee/artoo
+Project-URL: Repository, https://github.com/lavallee/artoo
+Project-URL: Changelog, https://github.com/lavallee/artoo/blob/main/CHANGELOG.md
+Author: Marc Lavallee
+License: MIT
+License-File: LICENSE
+Keywords: artifacts,explainer,llm,reports,static-site
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Description-Content-Type: text/markdown
+
+# artoo
+
+**Generate and manage artifacts** — self-contained HTML mini-sites that pair
+presentation with the research backing it.
+
+There's a burgeoning practice of getting explanations of systems out of LLMs
+as real pages — with navigation, diagrams, and provenance — instead of
+markdown dumps, and of composing reports from multiple assets. artoo is the
+tool layer for that practice:
+
+- **Artifacts live anywhere.** An artifact is a directory with an
+  `artifact.toml` inside whatever repo owns it. A library's explainer lives
+  in that library's repo. One repo can hold many artifacts.
+- **Self-contained, with provenance.** The publishable `site/` renders from
+  a `file://` URL — vendored assets, no bundler, no CDN dependencies. Shared
+  components come from versioned, hash-pinned site libraries you can upgrade
+  deliberately.
+- **Deployment-aware.** artoo understands GitHub Pages (including whether
+  your repo serves from `/docs`, a workflow, or a branch), ssh/rsync targets,
+  and arbitrary publish commands. Secrets never enter the repo.
+- **Research stays with the piece.** Notebooks, working files, and anything
+  `_`-prefixed sit next to the presentation but can never ship — the deploy
+  path is deny-by-default.
+- **Generators, not API keys.** Model-powered generators (like the repo
+  explainer) delegate to agent CLIs you already have — `claude`, `codex` —
+  with cheap tiers for fan-out analysis and strong tiers for synthesis.
+  artoo core makes no model calls and holds no keys.
+
+## Install
+
+```bash
+uv tool install artoo-artifacts   # or: pipx install artoo-artifacts
+artoo --version                   # the command is `artoo`
+```
+
+Research-notebook support activates automatically when
+[flip](https://github.com/lavallee/flip) is installed alongside artoo.
+
+## Quickstart
+
+```bash
+# Scaffold an artifact inside any repo
+artoo init site/my-report --kind report --title "Q3 systems report"
+
+# See every artifact in the repo
+artoo list
+
+# Check health: manifest, firewall, library drift
+artoo status site/my-report
+
+# Publish (adapter chosen by the manifest's [deploy] table)
+artoo deploy site/my-report
+```
+
+## Generate a repo explainer
+
+```bash
+artoo generate explainer --repo . --out site/explainer
+artoo deploy site/explainer
+```
+
+The explainer inventories the repo deterministically, fans out per-module
+analysis to a cheap worker (`codex`), synthesizes the narrative with a strong
+worker (`claude`), renders architecture diagrams, and assembles a multi-page
+site with the built-in design kit. The result is a dated snapshot with a
+colophon saying exactly how it was made.
+
+## Status
+
+v0.1.0 — alpha. The manifest format, CLI surface, and plugin entry points
+are young and may change before 1.0. See [DESIGN.md](DESIGN.md) for the
+architecture and [CHANGELOG.md](CHANGELOG.md) for history.
+
+## Development
+
+```bash
+git clone https://github.com/lavallee/artoo && cd artoo
+uv sync
+uv run pytest -q
+uv run ruff check src tests
+```
+
+MIT licensed. Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).

artoo_artifacts-0.1.0/README.md

@@ -0,0 +1,83 @@
+# artoo
+
+**Generate and manage artifacts** — self-contained HTML mini-sites that pair
+presentation with the research backing it.
+
+There's a burgeoning practice of getting explanations of systems out of LLMs
+as real pages — with navigation, diagrams, and provenance — instead of
+markdown dumps, and of composing reports from multiple assets. artoo is the
+tool layer for that practice:
+
+- **Artifacts live anywhere.** An artifact is a directory with an
+  `artifact.toml` inside whatever repo owns it. A library's explainer lives
+  in that library's repo. One repo can hold many artifacts.
+- **Self-contained, with provenance.** The publishable `site/` renders from
+  a `file://` URL — vendored assets, no bundler, no CDN dependencies. Shared
+  components come from versioned, hash-pinned site libraries you can upgrade
+  deliberately.
+- **Deployment-aware.** artoo understands GitHub Pages (including whether
+  your repo serves from `/docs`, a workflow, or a branch), ssh/rsync targets,
+  and arbitrary publish commands. Secrets never enter the repo.
+- **Research stays with the piece.** Notebooks, working files, and anything
+  `_`-prefixed sit next to the presentation but can never ship — the deploy
+  path is deny-by-default.
+- **Generators, not API keys.** Model-powered generators (like the repo
+  explainer) delegate to agent CLIs you already have — `claude`, `codex` —
+  with cheap tiers for fan-out analysis and strong tiers for synthesis.
+  artoo core makes no model calls and holds no keys.
+
+## Install
+
+```bash
+uv tool install artoo-artifacts   # or: pipx install artoo-artifacts
+artoo --version                   # the command is `artoo`
+```
+
+Research-notebook support activates automatically when
+[flip](https://github.com/lavallee/flip) is installed alongside artoo.
+
+## Quickstart
+
+```bash
+# Scaffold an artifact inside any repo
+artoo init site/my-report --kind report --title "Q3 systems report"
+
+# See every artifact in the repo
+artoo list
+
+# Check health: manifest, firewall, library drift
+artoo status site/my-report
+
+# Publish (adapter chosen by the manifest's [deploy] table)
+artoo deploy site/my-report
+```
+
+## Generate a repo explainer
+
+```bash
+artoo generate explainer --repo . --out site/explainer
+artoo deploy site/explainer
+```
+
+The explainer inventories the repo deterministically, fans out per-module
+analysis to a cheap worker (`codex`), synthesizes the narrative with a strong
+worker (`claude`), renders architecture diagrams, and assembles a multi-page
+site with the built-in design kit. The result is a dated snapshot with a
+colophon saying exactly how it was made.
+
+## Status
+
+v0.1.0 — alpha. The manifest format, CLI surface, and plugin entry points
+are young and may change before 1.0. See [DESIGN.md](DESIGN.md) for the
+architecture and [CHANGELOG.md](CHANGELOG.md) for history.
+
+## Development
+
+```bash
+git clone https://github.com/lavallee/artoo && cd artoo
+uv sync
+uv run pytest -q
+uv run ruff check src tests
+```
+
+MIT licensed. Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).

artoo_artifacts-0.1.0/RELEASING.md

@@ -0,0 +1,25 @@
+# Releasing artoo
+
+1. `uv run pytest -q` and `uv run ruff check src tests` pass locally.
+2. Bump the version in **both** places, in lockstep:
+   - `pyproject.toml` → `[project] version`
+   - `src/artoo/__init__.py` → `__version__`
+3. Update `CHANGELOG.md`: dated heading, Added/Changed/Fixed sections.
+4. Update the landing page (`docs/index.html`) version badge and any new
+   capabilities.
+5. Commit a clean `chore(release): X.Y.Z`.
+6. Tag: `git tag -a vX.Y.Z -m "artoo X.Y.Z"` → push `main` and the tag.
+7. `gh release create vX.Y.Z` with focused notes and a compare link.
+8. Publishing the release triggers `.github/workflows/publish.yml`
+   (PyPI trusted publishing via the `pypi-artoo-artifacts` environment;
+   the distribution is `artoo-artifacts`, import/CLI stay `artoo`). Verify the
+   run; re-dispatch with `gh workflow run publish.yml` if needed.
+   Fallback: `uv build && uv publish` with a token.
+
+Semantic versioning:
+
+- **Patch** — fixes, docs; no surface change.
+- **Minor** — new backward-compatible surface (CLI command, adapter,
+  entry point, manifest field with a default).
+- **Major** — breaking CLI flags, manifest schema, or entry-point
+  signatures. Changes to firewall semantics are always breaking.