data-refinery-cli 0.3.2__tar.gz → 0.3.3__tar.gz

{data_refinery_cli-0.3.2 → data_refinery_cli-0.3.3}/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.3] - 2026-06-20
+
+### Changed
+
+- `/init`: rewrote the seed `CLAUDE.md` placeholder into a full Claude Code
+  runtime prompt — the three-name split (`data-refinery` command vs
+  `data-refinery-cli` dist/nick vs `data_refinery` package), the CLI contracts
+  (`CliError`/exit-codes, stdout/stderr split, the explain catalog, the `doctor`
+  invariants), the `colleague` backend + dual prompt files, version-bump-every-PR,
+  the CI gates, the skills kit, and the issue #1 storage/data-quality domain
+  roadmap.
+- Reconciled the CLI command-surface text from `data-refinery-cli` to the actual
+  binary name `data-refinery` (argparse `prog`/description, `learn`, the `explain`
+  catalog bodies + headings, `overview`/`cli` subjects, `doctor` output, and the
+  README quickstart). `data-refinery-cli` is kept as `whoami`'s nick and a
+  back-compat `explain` alias.
+- CLI self-description (`learn`/`explain`/`overview`) no longer calls the agent
+  "a clonable template" — it names the data-quality domain and notes the domain
+  verbs are not built yet.
+
+### Fixed
+
+- Agent-first rubric (`teken cli doctor . --strict`) was red on `explain_self`:
+  it runs `explain data-refinery` (the `[project.scripts]` command) but the
+  catalog only keyed `("data-refinery-cli",)`. Added the `("data-refinery",)` root
+  entry (alias kept) — rubric back to 26/26.
+- `pyproject.toml` license `MIT` → `Apache-2.0` (+ matching classifier) to match
+  the `LICENSE` file and README (org-wide scaffold bug inherited from the
+  template; a correction, not a relicense).
+
 ## [0.3.2] - 2026-06-18
 
 ### Added

data_refinery_cli-0.3.3/CLAUDE.md

@@ -0,0 +1,247 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+**data-refinery-cli** is an AgentCulture mesh agent: a CLI for **data quality in
+storage and retrieval** — validating, deduplicating, and checking the integrity
+and freshness of data as it is stored and fetched. It is being split out of
+**eidetic-cli** so eidetic keeps the agent-memory layer; it is a sibling to
+**daria** (the Data Refinery Intelligent Agent).
+
+**Current state — read this first.** The data-quality/storage domain is **not
+built yet**. Runtime `dependencies = []`; the code on disk today is the inherited
+*agent-first introspection scaffold* (`whoami` / `learn` / `explain` / `overview`
+/ `doctor` + a `cli` noun), cloned from `culture-agent-template` and cited from
+[teken](https://github.com/agentculture/teken)'s `python-cli` reference. Its
+self-description (`learn`, `explain`, `overview`) now names the data-quality
+domain honestly — "the data-quality verbs are not built yet" — rather than the
+old "clonable template" scaffold framing. The repo's true purpose is the
+data-quality agent above and the build order in **issue #1** (see "Domain
+roadmap").
+
+## Names: there are three, and they differ on purpose
+
+This trips up every change to the CLI surface. Keep them straight:
+
+| Name | Value | Where it lives |
+|------|-------|----------------|
+| **CLI command** (the binary) | `data-refinery` | `[project.scripts]` in `pyproject.toml` — this is what you invoke: `uv run data-refinery whoami` |
+| **PyPI dist + mesh nick** | `data-refinery-cli` | `pyproject.toml` `name`, `culture.yaml` `suffix`, the Sonar key `agentculture_data-refinery-cli`, `__version__` lookup, `_ISSUES_URL` |
+| **Python package / import** | `data_refinery` | the `data_refinery/` dir, `import data_refinery`, `sonar.sources` |
+
+`data-refinery-cli` is **not** an executable — `uv run data-refinery-cli …`
+fails; the binary is `data-refinery`. The CLI's command-surface text (help,
+`learn`, the `explain` catalog, `overview` subjects) and the README quickstart
+all use `data-refinery`. The dist/nick name `data-refinery-cli` is kept as a
+back-compat **alias** in the explain catalog (`explain data-refinery-cli` still
+resolves) and as `whoami`'s nick. When you add a verb, keep this split: command
+text → `data-refinery`, nick/dist/URL/`_pkg_version`/`_FALLBACK_NICK` →
+`data-refinery-cli`.
+
+## Common commands
+
+```bash
+uv sync                                   # create .venv, install runtime + dev deps
+uv run pytest -n auto                      # full test suite (xdist parallel)
+uv run pytest tests/test_cli.py::test_whoami_json   # a single test
+uv run pytest -k explain                   # tests matching a name
+uv run data-refinery whoami                # run the CLI (note: data-refinery, not -cli)
+uv run data-refinery learn --json          # every verb supports --json
+python -m data_refinery whoami             # equivalent module entry point
+```
+
+Lint / quality gates (each is its own CI job — run all before a PR):
+
+```bash
+uv run black --check data_refinery tests
+uv run isort --check-only data_refinery tests
+uv run flake8 data_refinery tests
+uv run bandit -c pyproject.toml -r data_refinery
+markdownlint-cli2 "**/*.md" "#node_modules" "#.local" "#.claude/skills" "#.teken"
+uv run teken cli doctor . --strict         # the agent-first rubric gate (see below)
+```
+
+`black` / `isort` use line-length 100 (`pyproject.toml`); `flake8` matches it via
+`.flake8`. Run `black`/`isort` without `--check` to auto-fix. For bulk markdown
+fixes use the `lint-fix` agent.
+
+## Architecture
+
+The whole CLI is built around one contract: **an agent reading the output can
+rely on it.** Structured errors, a strict stream split, `--json` everywhere, and
+documented exit codes. The pieces that enforce this span several files:
+
+- **`data_refinery/cli/__init__.py`** — `main(argv) -> int` is the entry point
+  (`main(argv: list[str] | None = None)`, the contract teken checks). It builds an
+  argparse tree, dispatches, and translates every failure to an exit code.
+  - `_CliArgumentParser` overrides `.error()` so **argparse-level** failures
+    (unknown verb, bad flag) route through the same `error:` / `hint:` structured
+    format and exit 1 — not argparse's default `stderr` + exit 2. `parser_class`
+    is propagated to every subparser so nested parse errors behave the same.
+    Because parse errors happen *before* `args.json` exists, `main()` pre-scans
+    raw argv for `--json` and sets the class-level `_json_hint`.
+  - `_dispatch()` calls the handler; catches `CliError` → `emit_error`; wraps
+    **any other exception** into a `CliError` so **no Python traceback ever
+    leaks** to stderr (a hard rubric requirement).
+- **`_errors.py`** — `CliError{code, message, remediation}` and the exit-code
+  policy: `0` success, `1` user-input error, `2` environment/setup error, `3+`
+  reserved. Every failure path raises `CliError`.
+- **`_output.py`** — the strict stream split: `emit_result` → stdout,
+  `emit_error` / `emit_diagnostic` → stderr, **never mixed**. In JSON mode each
+  goes to its own stream as one JSON line. The `hint:` prefix on errors is
+  load-bearing (agents and the rubric grep for it).
+- **Command modules** in `cli/_commands/` each expose `register(sub)` and a
+  handler returning `int | None`. To add a verb/noun: write the module, then call
+  its `register()` in `_build_parser()`. Nouns with action-verbs must also expose
+  an `overview` (rubric `overview_cli_noun_exists`) — the `cli` noun exists purely
+  to model that pattern (it has no action-verbs yet, only `cli overview`).
+- **`data_refinery/explain/`** — `catalog.py` holds verbatim markdown keyed by
+  **command-path tuples** (`("whoami",)`, `("cli","overview")`); `resolve()`
+  raises `CliError` on an unknown path. Every registered noun/verb needs an
+  entry, and the root must be keyed under the **command name** `("data-refinery",)`
+  (the rubric's `explain_self` runs `explain data-refinery`) — with
+  `("data-refinery-cli",)` kept as a back-compat alias.
+- **Identity without a YAML dependency.** `whoami.py` and `doctor.py` parse
+  `culture.yaml` by hand (line-scanning, not PyYAML) to preserve the deps-empty
+  invariant. `find_culture_yaml()` walks up from `__file__` to find *this agent's
+  own* `culture.yaml` (not whatever is in the caller's CWD); in a wheel install
+  none ships, so identity falls back to literal defaults.
+- **`doctor`** mirrors the `steward doctor` invariants for a mesh agent:
+  *prompt-file-present* + *backend-consistency* (`backend → prompt file`:
+  `claude→CLAUDE.md`, `colleague→AGENTS.colleague.md`, `acp→AGENTS.md`,
+  `gemini→GEMINI.md`) and a *skills-present* check. It returns the rubric-shaped
+  `{healthy, checks:[{id,passed,severity,message,remediation}]}`.
+
+### The agent-first rubric (`teken cli doctor . --strict`)
+
+This is the **lint job's gate** and the design spec for the whole CLI. It checks
+seven bundles — structure, learnability, json, errors, explain, overview, doctor
+— against the *actual running CLI* (it invokes `data-refinery <verb>` and asserts
+on output/exit codes). When you change the CLI surface, this is the fast check:
+keep `learn` ≥200 chars with all markers, keep errors traceback-free with hints,
+keep `explain <command-name>` resolving, keep every noun's `overview`.
+
+## Identity & the two prompt files
+
+`culture.yaml` declares the agent: `suffix: data-refinery-cli`,
+**`backend: colleague`**, model `sakamakismile/Qwen3.6-27B-Text-NVFP4-MTP`. Two
+prompt files coexist and serve different runtimes:
+
+- **`CLAUDE.md`** (this file) — the prompt for **Claude Code** when a human (or
+  you) operates in the repo interactively.
+- **`AGENTS.colleague.md`** — the resident prompt for the **colleague backend**
+  (the Qwen tool-loop peer that actually *runs* as this mesh agent). Because the
+  declared backend is `colleague`, this is the file `doctor`/`steward` require,
+  and it is currently a thin generic stub.
+
+When you change durable agent behavior that should hold regardless of who runs
+the agent, update **both** files (they target different runtimes but describe the
+same agent). The seed version of this file claimed `backend: claude` — that was
+stale; the live backend is `colleague`.
+
+## Conventions that gate merges
+
+- **Version-bump-every-PR.** Every PR — even docs/config/CI-only — must bump the
+  `pyproject.toml` version, or the `version-check` CI job fails. Use the
+  `version-bump` skill (updates `pyproject.toml` + prepends a Keep-a-Changelog
+  entry to `CHANGELOG.md`). The check compares your version to `origin/main`.
+- **Runtime deps stay empty.** `dependencies = []` is an invariant of the current
+  scaffold; `teken` and the linters are **dev-only**. When the domain lands and
+  needs `neo4j` / `pymongo` (issue #1), follow the sibling pattern proven across
+  this org: put heavy deps behind an **optional extra**, **lazy-import** them
+  inside function bodies, exit `CliError(code=2)` with an install `hint:` when
+  absent, and add a static test asserting no top-level import of the optional dep.
+- **No traceback, ever.** Failures raise `CliError`; the dispatcher wraps stray
+  exceptions. Don't `print()` to stdout for errors or let exceptions escape.
+- **`--json` on every command**, stdout/stderr never mixed.
+- **SonarCloud coverage uses repo-relative paths.** `pyproject.toml`
+  `[tool.coverage.run] relative_files = true, source = ["data_refinery"]` is what
+  makes `coverage.xml` map onto `sonar.sources` — don't remove it. `omit` ≠ Sonar
+  coverage exclusion; mirror any `omit` into `sonar.coverage.exclusions`.
+
+### CI jobs (what must be green)
+
+- `.github/workflows/tests.yml` → **test** (pytest + coverage, then SonarCloud
+  scan gated on `SONAR_TOKEN`; `sonar.qualitygate.wait=true` fails the job on a
+  red gate), **lint** (black, isort, flake8, bandit, markdownlint, **the teken
+  rubric gate**), **version-check** (PR-only; enforces the bump).
+- `.github/workflows/publish.yml` → TestPyPI on PRs, PyPI on push to `main`, via
+  Trusted Publishing (OIDC, no tokens). Triggered by changes to `pyproject.toml`
+  or `data_refinery/**`.
+
+Use the **`cicd`** skill for the PR lifecycle (open / read / reply / status /
+await SonarCloud); **`sonarclaude`** for quality-gate queries; **`run-tests`** to
+run pytest. PR comments/issue posts auto-sign as `- data-refinery-cli (Claude)`.
+
+## Skills (cite-don't-import)
+
+`.claude/skills/` carries 12 skills vendored from **guildmaster** (the
+AgentCulture skills supplier; `steward` keeps only the alignment role). They are
+copied, not depended on — each consumer owns its copy. Provenance, per-skill
+adaptation notes, and the re-sync procedure live in
+[`docs/skill-sources.md`](docs/skill-sources.md). Two tracked divergences:
+`agex→devex` and `outsource→ask-colleague` (vendored directly from `colleague`
+until guildmaster re-broadcasts). Every `SKILL.md` must keep `type: command` in
+frontmatter — `core.skill_loader` silently skips any that omit it.
+
+Reach for **`ask-colleague`** reflexively: `review` for a diverse second opinion
+on a committed diff before a PR, `explore` for a fresh read of an unfamiliar area
+(both read-only, isolated in a throwaway worktree — always safe); `write --apply`
+/ `--pr` mutates and needs the user's go-ahead. Optional `colleague` CLI on PATH.
+
+## Domain roadmap (issue #1)
+
+The agent's actual build order lives in
+[issue #1](https://github.com/agentculture/data-refinery-cli/issues/1): take
+ownership of the **storage + data-quality layer** split from eidetic-cli (this
+returns the store substrate to its origin — eidetic's store/cypher/embedding
+logic was *cited from* `data-refinery` in the first place). data-refinery-cli is
+to own:
+
+- a **`docker-compose.yml`** bringing up `mongo:8.0` on host port **27018** (not
+  27017 — deliberate collision-avoidance, eidetic's defaults already point there)
+  and `neo4j:5-community` (bolt 7687, apoc), and a **multi-arch GHCR image**
+  bundling that stack;
+- the **files backend** + **cypher/mongo store adapters**, and the
+  **consumer-agnostic data-quality surface**: validate, dedup (by `id`/`hash`,
+  idempotent upsert), integrity, freshness — with **no eidetic memory semantics
+  leaking in**;
+- the `neo4j` + `pymongo` runtime deps.
+
+eidetic-cli keeps the record schema, the `remember`/`recall`/`sweep`/`migrate`
+verbs, relevance scoring + the freshness *signal*, the no-hard-delete lifecycle,
+and the per-scope public/private no-leak invariant — and becomes the **first
+consumer** over a process (subprocess-not-import) boundary. Invariants your layer
+must not break: idempotent dedup, and the public/private scope no-leak. The
+proposed boundary is **phased**: ship the GHCR image first, move adapters + the
+CLI surface second. Naming of the image and the store/quality verbs is this
+repo's call (it owns the surface) but must be documented so eidetic can pin.
+
+## Remaining gaps / next steps
+
+The `/init` PR reconciled the three scaffold defects (the `explain_self` rubric
+failure via the `("data-refinery",)` catalog key + command-surface sweep; the
+`pyproject` license `MIT` → `Apache-2.0`; the "clonable template" self-description
+→ the data-quality domain). What is still open:
+
+1. **The domain itself is unbuilt** — implement issue #1 (the storage +
+   data-quality layer). This is the substantive work.
+2. **`AGENTS.colleague.md` is a thin generic stub.** Since the agent runs on the
+   `colleague` backend, its resident prompt should be fleshed out to match this
+   file's identity/invariants (the sibling cloudai-cli did this during its init).
+3. **README + `overview` still carry some template framing** ("Make it your own",
+   the "sibling-pattern artifacts" section) — minor doc drift to retire as the
+   domain lands.
+
+## Renaming / scaffold lineage
+
+This repo descends from `culture-agent-template`; the template name is hard-coded
+in ~100 places. To find every occurrence before a sweep:
+
+```bash
+git grep -nw data-refinery-cli        # dist/nick name
+git grep -nw data_refinery            # python package
+git grep -nw data-refinery            # CLI command
+```

{data_refinery_cli-0.3.2 → data_refinery_cli-0.3.3}/PKG-INFO

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: data-refinery-cli
-Version: 0.3.2
+Version: 0.3.3
 Summary: Agent and CLI for data quality in storage and retrieval — validating, deduplicating, and checking the integrity and freshness of data as it is stored and fetched. Split out of eidetic-cli so eidetic keeps agent-memory; sibling to daria, the Data Refinery Intelligent Agent.
 Project-URL: Homepage, https://github.com/agentculture/data-refinery-cli
 Project-URL: Issues, https://github.com/agentculture/data-refinery-cli/issues
 Author: AgentCulture
-License-Expression: MIT
+License-Expression: Apache-2.0
 License-File: LICENSE
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
+Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development
 Requires-Python: >=3.12
@@ -35,8 +35,8 @@ Agent and CLI for data quality in storage and retrieval — validating, deduplic
 ```bash
 uv sync
 uv run pytest -n auto                 # run the test suite
-uv run data-refinery-cli whoami  # identity from culture.yaml
-uv run data-refinery-cli learn   # self-teaching prompt (add --json)
+uv run data-refinery whoami      # identity from culture.yaml
+uv run data-refinery learn       # self-teaching prompt (add --json)
 uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
 ```
 

{data_refinery_cli-0.3.2 → data_refinery_cli-0.3.3}/README.md

@@ -18,8 +18,8 @@ Agent and CLI for data quality in storage and retrieval — validating, deduplic
 ```bash
 uv sync
 uv run pytest -n auto                 # run the test suite
-uv run data-refinery-cli whoami  # identity from culture.yaml
-uv run data-refinery-cli learn   # self-teaching prompt (add --json)
+uv run data-refinery whoami      # identity from culture.yaml
+uv run data-refinery learn       # self-teaching prompt (add --json)
 uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
 ```
 

{data_refinery_cli-0.3.2 → data_refinery_cli-0.3.3}/data_refinery/cli/__init__.py

@@ -70,8 +70,8 @@ def _build_parser() -> argparse.ArgumentParser:
     from data_refinery.cli._commands import whoami as _whoami_cmd
 
     parser = _CliArgumentParser(
-        prog="data-refinery-cli",
-        description="data-refinery-cli — a clonable template for AgentCulture mesh agents.",
+        prog="data-refinery",
+        description="data-refinery — agent and CLI for data quality in storage and retrieval.",
     )
     parser.add_argument(
         "--version",

{data_refinery_cli-0.3.2 → data_refinery_cli-0.3.3}/data_refinery/cli/_commands/cli.py

@@ -1,4 +1,4 @@
-"""``data-refinery-cli cli`` — noun grouping CLI-surface introspection.
+"""``data-refinery cli`` — noun grouping CLI-surface introspection.
 
 Exists to satisfy the agent-first rubric's ``overview_cli_noun_exists`` check:
 any noun with action-verbs must also expose ``overview``. There are no
@@ -15,7 +15,7 @@ from data_refinery.cli._commands.overview import cli_sections, emit_overview
 
 def cmd_cli_overview(args: argparse.Namespace) -> int:
     emit_overview(
-        "data-refinery-cli cli",
+        "data-refinery cli",
         cli_sections(),
         json_mode=bool(getattr(args, "json", False)),
     )
@@ -23,14 +23,14 @@ def cmd_cli_overview(args: argparse.Namespace) -> int:
 
 
 def _no_verb(args: argparse.Namespace) -> int:
-    # `data-refinery-cli cli` with no sub-verb prints the noun's overview.
+    # `data-refinery cli` with no sub-verb prints the noun's overview.
     return cmd_cli_overview(args)
 
 
 def register(sub: argparse._SubParsersAction) -> None:
     p = sub.add_parser(
         "cli",
-        help="CLI-surface introspection (see 'data-refinery-cli cli overview').",
+        help="CLI-surface introspection (see 'data-refinery cli overview').",
     )
     p.add_argument("--json", action="store_true", help="Emit structured JSON.")
     p.set_defaults(func=_no_verb, json=False)
@@ -38,6 +38,6 @@ def register(sub: argparse._SubParsersAction) -> None:
     # parser_class); propagate it so `cli overview` parse errors route through
     # the structured error contract instead of argparse's default stderr/exit 2.
     noun_sub = p.add_subparsers(dest="cli_command", parser_class=type(p))
-    ov = noun_sub.add_parser("overview", help="Describe the data-refinery-cli CLI surface.")
+    ov = noun_sub.add_parser("overview", help="Describe the data-refinery CLI surface.")
     ov.add_argument("--json", action="store_true", help="Emit structured JSON.")
     ov.set_defaults(func=cmd_cli_overview)

{data_refinery_cli-0.3.2 → data_refinery_cli-0.3.3}/data_refinery/cli/_commands/doctor.py

@@ -1,4 +1,4 @@
-"""``data-refinery-cli doctor`` — check the agent-identity invariants.
+"""``data-refinery doctor`` — check the agent-identity invariants.
 
 Mirrors the two invariants ``steward doctor`` verifies for a mesh agent:
 
@@ -105,7 +105,7 @@ def cmd_doctor(args: argparse.Namespace) -> int:
         emit_result(report, json_mode=True)
     else:
         status = "healthy" if report["healthy"] else "unhealthy"
-        lines = [f"data-refinery-cli doctor: {status}", ""]
+        lines = [f"data-refinery doctor: {status}", ""]
         for check in report["checks"]:
             mark = "ok" if check["passed"] else "FAIL"
             lines.append(f"[{mark}] {check['id']}: {check['message']}")

{data_refinery_cli-0.3.2 → data_refinery_cli-0.3.3}/data_refinery/cli/_commands/explain.py

@@ -1,4 +1,4 @@
-"""``data-refinery-cli explain <path>...`` — global markdown catalog lookup (stable-contract).
+"""``data-refinery explain <path>...`` — global markdown catalog lookup (stable-contract).
 
 ``explain`` is global (not nested under a noun). It takes zero or more path
 tokens and resolves them via the catalog in :mod:`data_refinery.explain`.
@@ -32,7 +32,7 @@ def register(sub: argparse._SubParsersAction) -> None:
     p.add_argument(
         "path",
         nargs="*",
-        help="Command path tokens; empty = root (same as 'data-refinery-cli').",
+        help="Command path tokens; empty = root (same as 'data-refinery').",
     )
     p.add_argument("--json", action="store_true", help="Emit structured JSON.")
     p.set_defaults(func=cmd_explain)

{data_refinery_cli-0.3.2 → data_refinery_cli-0.3.3}/data_refinery/cli/_commands/learn.py

@@ -1,4 +1,4 @@
-"""``data-refinery-cli learn`` — the learnability affordance.
+"""``data-refinery learn`` — the learnability affordance.
 
 Prints a structured self-teaching prompt. Must satisfy the agent-first rubric:
 >=200 chars and mention purpose, command map, exit codes, --json, and explain.
@@ -12,23 +12,24 @@ from data_refinery import __version__
 from data_refinery.cli._output import emit_result
 
 _TEXT = """\
-data-refinery-cli — a clonable template for AgentCulture mesh agents.
+data-refinery — agent and CLI for data quality in storage and retrieval.
 
 Purpose
 -------
-Scaffold for a new Culture mesh agent: an agent-first CLI (cited from the teken
-`python-cli` reference), an identity (culture.yaml + CLAUDE.md), the canonical
-guildmaster skill kit under .claude/skills/, and a deploy/CI baseline. Clone it,
-rename the package, and edit culture.yaml to mint a new agent.
+Validate, deduplicate, and check the integrity and freshness of data as it is
+stored and fetched. Split out of eidetic-cli so eidetic keeps agent-memory;
+sibling to daria. The data-quality verbs are not built yet (see issue #1) —
+today this exposes the agent-first introspection surface below on a
+self-contained runtime (no third-party dependencies).
 
 Commands
 --------
-  data-refinery-cli whoami             Identity from culture.yaml.
-  data-refinery-cli learn              This self-teaching prompt.
-  data-refinery-cli explain <path>...  Markdown docs for any noun/verb path.
-  data-refinery-cli overview           Descriptive snapshot of the agent.
-  data-refinery-cli doctor             Check the agent-identity invariants.
-  data-refinery-cli cli overview       Describe the CLI surface itself.
+  data-refinery whoami             Identity from culture.yaml.
+  data-refinery learn              This self-teaching prompt.
+  data-refinery explain <path>...  Markdown docs for any noun/verb path.
+  data-refinery overview           Descriptive snapshot of the agent.
+  data-refinery doctor             Check the agent-identity invariants.
+  data-refinery cli overview       Describe the CLI surface itself.
 
 Machine-readable output
 -----------------------
@@ -44,15 +45,15 @@ Exit-code policy
 
 More detail
 -----------
-  data-refinery-cli explain data-refinery-cli
+  data-refinery explain data-refinery
 """
 
 
 def _as_json_payload() -> dict[str, object]:
     return {
-        "tool": "data-refinery-cli",
+        "tool": "data-refinery",
         "version": __version__,
-        "purpose": "Clonable scaffold for a new AgentCulture mesh agent.",
+        "purpose": "Agent and CLI for data quality in storage and retrieval.",
         "commands": [
             {"path": ["whoami"], "summary": "Identity probe from culture.yaml."},
             {"path": ["learn"], "summary": "Self-teaching prompt."},
@@ -67,7 +68,7 @@ def _as_json_payload() -> dict[str, object]:
             "2": "environment/setup error",
         },
         "json_support": True,
-        "explain_pointer": "data-refinery-cli explain <path>",
+        "explain_pointer": "data-refinery explain <path>",
     }
 
 

{data_refinery_cli-0.3.2 → data_refinery_cli-0.3.3}/data_refinery/cli/_commands/overview.py

@@ -1,4 +1,4 @@
-"""``data-refinery-cli overview`` — read-only descriptive snapshot of the agent.
+"""``data-refinery overview`` — read-only descriptive snapshot of the agent.
 
 Describes the agent to an agent reader: identity (from culture.yaml), the verb
 surface, and the sibling-pattern artifacts this template carries. The shared
@@ -90,7 +90,7 @@ def cmd_overview(args: argparse.Namespace) -> int:
     # `target` is accepted for rubric compatibility (descriptive verbs must not
     # hard-fail on a missing path) but overview describes this agent itself.
     emit_overview(
-        "data-refinery-cli",
+        "data-refinery",
         agent_sections(),
         json_mode=bool(getattr(args, "json", False)),
     )

{data_refinery_cli-0.3.2 → data_refinery_cli-0.3.3}/data_refinery/cli/_commands/whoami.py

@@ -1,4 +1,4 @@
-"""``data-refinery-cli whoami`` — the smallest identity probe.
+"""``data-refinery whoami`` — the smallest identity probe.
 
 Reports the agent's identity as declared in ``culture.yaml``: its nick
 (``suffix``), the backend it runs on, and the served model (if any) — plus the

{data_refinery_cli-0.3.2 → data_refinery_cli-0.3.3}/data_refinery/cli/_errors.py

@@ -1,6 +1,6 @@
 """CliError and exit-code policy (stable-contract).
 
-Every failure inside data-refinery-cli raises :class:`CliError`. The
+Every failure inside data-refinery raises :class:`CliError`. The
 top-level ``main()`` catches it, formats via :mod:`data_refinery.cli._output`,
 and exits with :attr:`CliError.code`. This guarantees:
 
@@ -13,7 +13,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
-# Exit-code policy. Documented in ``data-refinery-cli learn`` output.
+# Exit-code policy. Documented in ``data-refinery learn`` output.
 # 0      = success
 # 1      = user-input error (bad flag, missing required arg, unknown path)
 # 2      = environment / setup error (tool not installed, file unreadable)

{data_refinery_cli-0.3.2 → data_refinery_cli-0.3.3}/data_refinery/explain/__init__.py

@@ -16,7 +16,7 @@ def resolve(path: tuple[str, ...]) -> str:
     raise CliError(
         code=EXIT_USER_ERROR,
         message=f"no explain entry for: {display}",
-        remediation="list entries with: data-refinery-cli explain data-refinery-cli",
+        remediation="list entries with: data-refinery explain data-refinery",
     )
 
 

data_refinery_cli-0.3.3/data_refinery/explain/catalog.py

@@ -0,0 +1,136 @@
+"""Markdown catalog for ``data-refinery explain <path>``.
+
+Each entry is verbatim markdown. Keys are command-path tuples. The empty tuple
+and ``("data-refinery",)`` both resolve to the root entry; ``("data-refinery-cli",)``
+is kept as a back-compat alias for the dist/nick name.
+
+Keep bodies self-contained: an agent reading one entry should get enough
+context without chaining reads.
+"""
+
+from __future__ import annotations
+
+_ROOT = """\
+# data-refinery
+
+Agent and CLI for **data quality in storage and retrieval** — validating,
+deduplicating, and checking the integrity and freshness of data as it is stored
+and fetched. Split out of eidetic-cli so eidetic keeps agent-memory; sibling to
+daria, the Data Refinery Intelligent Agent.
+
+The data-quality verbs are not built yet (see issue #1). Today this exposes the
+agent-first introspection surface below on a self-contained runtime (no
+third-party dependencies). The binary is `data-refinery` (the PyPI dist and mesh
+nick are `data-refinery-cli`).
+
+## Verbs
+
+- `data-refinery whoami` — identity probe from `culture.yaml`.
+- `data-refinery learn` — structured self-teaching prompt.
+- `data-refinery explain <path>` — markdown docs for any noun/verb.
+- `data-refinery overview` — descriptive snapshot of the agent.
+- `data-refinery doctor` — check the agent-identity invariants.
+- `data-refinery cli overview` — describe the CLI surface.
+
+## Exit-code policy
+
+- `0` success
+- `1` user-input error
+- `2` environment / setup error
+- `3+` reserved
+
+## See also
+
+- `data-refinery explain whoami`
+- `data-refinery explain doctor`
+"""
+
+_WHOAMI = """\
+# data-refinery whoami
+
+Reports the agent's identity from `culture.yaml`: nick (`suffix`), backend,
+served model, and the package version. Read-only.
+
+## Usage
+
+    data-refinery whoami
+    data-refinery whoami --json
+"""
+
+_LEARN = """\
+# data-refinery learn
+
+Prints a structured self-teaching prompt covering purpose, command map,
+exit-code policy, `--json` support, and the `explain` pointer.
+
+## Usage
+
+    data-refinery learn
+    data-refinery learn --json
+"""
+
+_EXPLAIN = """\
+# data-refinery explain <path>
+
+Prints markdown documentation for any noun/verb path. Unlike `--help` (terse,
+positional), `explain` is global and addressable by path.
+
+## Usage
+
+    data-refinery explain data-refinery
+    data-refinery explain whoami
+    data-refinery explain --json <path>
+"""
+
+_OVERVIEW = """\
+# data-refinery overview
+
+Read-only descriptive snapshot of the agent: identity (from `culture.yaml`), the
+verb surface, and the sibling-pattern artifacts the agent carries. Accepts an
+ignored `target` so a stray path never hard-fails.
+
+## Usage
+
+    data-refinery overview
+    data-refinery overview --json
+"""
+
+_DOCTOR = """\
+# data-refinery doctor
+
+Checks the agent-identity invariants `steward doctor` verifies:
+prompt-file-present and backend-consistency (`colleague` → `AGENTS.colleague.md`),
+plus a skills-present check. Exits 1 when unhealthy.
+
+## Usage
+
+    data-refinery doctor
+    data-refinery doctor --json
+"""
+
+_CLI = """\
+# data-refinery cli
+
+Noun group for CLI-surface introspection. `cli overview` describes the CLI
+itself (distinct from the global `overview`, which describes the agent).
+
+## Usage
+
+    data-refinery cli overview
+    data-refinery cli overview --json
+"""
+
+
+ENTRIES: dict[tuple[str, ...], str] = {
+    (): _ROOT,
+    ("data-refinery",): _ROOT,
+    # Back-compat alias for the dist/nick name (the binary is `data-refinery`).
+    ("data-refinery-cli",): _ROOT,
+    ("whoami",): _WHOAMI,
+    ("learn",): _LEARN,
+    ("explain",): _EXPLAIN,
+    ("overview",): _OVERVIEW,
+    ("doctor",): _DOCTOR,
+    ("cli",): _CLI,
+    ("cli", "overview"): _CLI,
+}

{data_refinery_cli-0.3.2 → data_refinery_cli-0.3.3}/pyproject.toml

@@ -1,15 +1,15 @@
 [project]
 name = "data-refinery-cli"
-version = "0.3.2"
+version = "0.3.3"
 description = "Agent and CLI for data quality in storage and retrieval — validating, deduplicating, and checking the integrity and freshness of data as it is stored and fetched. Split out of eidetic-cli so eidetic keeps agent-memory; sibling to daria, the Data Refinery Intelligent Agent."
 readme = "README.md"
-license = "MIT"
+license = "Apache-2.0"
 requires-python = ">=3.12"
 authors = [{name = "AgentCulture"}]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Programming Language :: Python :: 3.12",
-    "License :: OSI Approved :: MIT License",
+    "License :: OSI Approved :: Apache Software License",
     "Topic :: Software Development",
     "Intended Audience :: Developers",
 ]

{data_refinery_cli-0.3.2 → data_refinery_cli-0.3.3}/tests/test_cli.py

@@ -21,7 +21,7 @@ def test_version_flag(capsys: pytest.CaptureFixture[str]) -> None:
 def test_no_args_prints_help(capsys: pytest.CaptureFixture[str]) -> None:
     rc = main([])
     assert rc == 0
-    assert "usage: data-refinery-cli" in capsys.readouterr().out
+    assert "usage: data-refinery" in capsys.readouterr().out
 
 
 def test_unknown_command_errors(capsys: pytest.CaptureFixture[str]) -> None:
@@ -62,7 +62,7 @@ def test_learn_text(capsys: pytest.CaptureFixture[str]) -> None:
     assert rc == 0
     out = capsys.readouterr().out
     assert len(out) >= 200
-    assert "data-refinery-cli" in out
+    assert "data-refinery" in out
     assert "Exit-code policy" in out
     assert "--json" in out
     assert "explain" in out
@@ -72,7 +72,7 @@ def test_learn_json(capsys: pytest.CaptureFixture[str]) -> None:
     rc = main(["learn", "--json"])
     assert rc == 0
     payload = json.loads(capsys.readouterr().out)
-    assert payload["tool"] == "data-refinery-cli"
+    assert payload["tool"] == "data-refinery"
     assert payload["version"] == __version__
     assert payload["json_support"] is True
 
@@ -83,10 +83,18 @@ def test_learn_json(capsys: pytest.CaptureFixture[str]) -> None:
 def test_explain_root(capsys: pytest.CaptureFixture[str]) -> None:
     rc = main(["explain"])
     assert rc == 0
-    assert "# data-refinery-cli" in capsys.readouterr().out
+    assert "# data-refinery" in capsys.readouterr().out
 
 
 def test_explain_self(capsys: pytest.CaptureFixture[str]) -> None:
+    # `explain <command-name>` must resolve (the rubric's explain_self check).
+    rc = main(["explain", "data-refinery"])
+    assert rc == 0
+    assert capsys.readouterr().out.startswith("#")
+
+
+def test_explain_dist_name_alias(capsys: pytest.CaptureFixture[str]) -> None:
+    # The dist/nick name stays a back-compat alias for the root entry.
     rc = main(["explain", "data-refinery-cli"])
     assert rc == 0
     assert capsys.readouterr().out.startswith("#")
@@ -97,7 +105,7 @@ def test_explain_json(capsys: pytest.CaptureFixture[str]) -> None:
     assert rc == 0
     payload = json.loads(capsys.readouterr().out)
     assert payload["path"] == ["whoami"]
-    assert "data-refinery-cli whoami" in payload["markdown"]
+    assert "data-refinery whoami" in payload["markdown"]
 
 
 def test_explain_unknown_path_errors(capsys: pytest.CaptureFixture[str]) -> None:

{data_refinery_cli-0.3.2 → data_refinery_cli-0.3.3}/tests/test_cli_introspection.py

@@ -15,7 +15,7 @@ def test_overview_text(capsys: pytest.CaptureFixture[str]) -> None:
     rc = main(["overview"])
     assert rc == 0
     out = capsys.readouterr().out
-    assert "# data-refinery-cli" in out
+    assert "# data-refinery" in out
     assert "Identity" in out
 
 
@@ -23,7 +23,7 @@ def test_overview_json_shape(capsys: pytest.CaptureFixture[str]) -> None:
     rc = main(["overview", "--json"])
     assert rc == 0
     payload = json.loads(capsys.readouterr().out)
-    assert payload["subject"] == "data-refinery-cli"
+    assert payload["subject"] == "data-refinery"
     assert isinstance(payload["sections"], list)
     assert payload["sections"]
 
@@ -41,14 +41,14 @@ def test_overview_graceful_on_bad_path(capsys: pytest.CaptureFixture[str]) -> No
 def test_cli_overview_text(capsys: pytest.CaptureFixture[str]) -> None:
     rc = main(["cli", "overview"])
     assert rc == 0
-    assert "# data-refinery-cli cli" in capsys.readouterr().out
+    assert "# data-refinery cli" in capsys.readouterr().out
 
 
 def test_cli_overview_json_shape(capsys: pytest.CaptureFixture[str]) -> None:
     rc = main(["cli", "overview", "--json"])
     assert rc == 0
     payload = json.loads(capsys.readouterr().out)
-    assert payload["subject"] == "data-refinery-cli cli"
+    assert payload["subject"] == "data-refinery cli"
     assert isinstance(payload["sections"], list)
 
 
@@ -77,7 +77,7 @@ def test_cli_overview_unknown_flag_structured_error(
 def test_doctor_text(capsys: pytest.CaptureFixture[str]) -> None:
     rc = main(["doctor"])
     assert rc in (0, 1)
-    assert "data-refinery-cli doctor" in capsys.readouterr().out
+    assert "data-refinery doctor" in capsys.readouterr().out
 
 
 def test_doctor_json_shape(capsys: pytest.CaptureFixture[str]) -> None:

{data_refinery_cli-0.3.2 → data_refinery_cli-0.3.3}/uv.lock

@@ -156,7 +156,7 @@ wheels = [
 
 [[package]]
 name = "data-refinery-cli"
-version = "0.3.2"
+version = "0.3.3"
 source = { editable = "." }
 
 [package.dev-dependencies]

data_refinery_cli-0.3.2/CLAUDE.md

@@ -1,28 +0,0 @@
-# CLAUDE.md — seed / bootstrap placeholder
-
-> **This is a self-initializing seed, not a finished runtime prompt.**
-> Run `/init` (or describe the agent's domain to your AI assistant) to
-> re-initialize this file into a full runtime prompt, using the description
-> below and the scaffolded repo as context.
-
-## Agent
-
-This repository hosts the **data-refinery-cli** agent.
-
-## Description
-
-Agent and CLI for data quality in storage and retrieval — validating, deduplicating, and checking the integrity and freshness of data as it is stored and fetched. Split out of eidetic-cli so eidetic keeps agent-memory; sibling to daria, the Data Refinery Intelligent Agent.
-
-## Re-init instruction
-
-This file is a seed. To expand it into your full runtime prompt:
-
-1. Open this repo in Claude Code (or your preferred AI assistant).
-2. Run `/init` — the assistant will read the repo, incorporate the description
-   above, and replace this seed with a complete `CLAUDE.md`.
-3. Commit the result.
-
-Until you run `/init`, `data-refinery-cli` satisfies the `steward doctor`
-`prompt-file-present` and `backend-consistency` invariants (a `CLAUDE.md`
-exists and `culture.yaml` declares `backend: claude`) but the prompt is not
-yet tailored to this agent's domain.

data_refinery_cli-0.3.2/data_refinery/explain/catalog.py

@@ -1,129 +0,0 @@
-"""Markdown catalog for ``data-refinery-cli explain <path>``.
-
-Each entry is verbatim markdown. Keys are command-path tuples. The empty tuple
-and ``("data-refinery-cli",)`` both resolve to the root entry.
-
-Keep bodies self-contained: an agent reading one entry should get enough
-context without chaining reads.
-"""
-
-from __future__ import annotations
-
-_ROOT = """\
-# data-refinery-cli
-
-A clonable template for AgentCulture mesh agents. It carries an agent-first CLI
-(cited from the teken `python-cli` reference), a mesh identity (`culture.yaml` +
-`CLAUDE.md`), the canonical guildmaster skill kit under `.claude/skills/`, and a
-buildable/deployable package baseline. Clone it, rename the package, edit
-`culture.yaml`, and you have a new agent.
-
-## Verbs
-
-- `data-refinery-cli whoami` — identity probe from `culture.yaml`.
-- `data-refinery-cli learn` — structured self-teaching prompt.
-- `data-refinery-cli explain <path>` — markdown docs for any noun/verb.
-- `data-refinery-cli overview` — descriptive snapshot of the agent.
-- `data-refinery-cli doctor` — check the agent-identity invariants.
-- `data-refinery-cli cli overview` — describe the CLI surface.
-
-## Exit-code policy
-
-- `0` success
-- `1` user-input error
-- `2` environment / setup error
-- `3+` reserved
-
-## See also
-
-- `data-refinery-cli explain whoami`
-- `data-refinery-cli explain doctor`
-"""
-
-_WHOAMI = """\
-# data-refinery-cli whoami
-
-Reports the agent's identity from `culture.yaml`: nick (`suffix`), backend,
-served model, and the package version. Read-only.
-
-## Usage
-
-    data-refinery-cli whoami
-    data-refinery-cli whoami --json
-"""
-
-_LEARN = """\
-# data-refinery-cli learn
-
-Prints a structured self-teaching prompt covering purpose, command map,
-exit-code policy, `--json` support, and the `explain` pointer.
-
-## Usage
-
-    data-refinery-cli learn
-    data-refinery-cli learn --json
-"""
-
-_EXPLAIN = """\
-# data-refinery-cli explain <path>
-
-Prints markdown documentation for any noun/verb path. Unlike `--help` (terse,
-positional), `explain` is global and addressable by path.
-
-## Usage
-
-    data-refinery-cli explain data-refinery-cli
-    data-refinery-cli explain whoami
-    data-refinery-cli explain --json <path>
-"""
-
-_OVERVIEW = """\
-# data-refinery-cli overview
-
-Read-only descriptive snapshot of the agent: identity (from `culture.yaml`), the
-verb surface, and the sibling-pattern artifacts the template carries. Accepts an
-ignored `target` so a stray path never hard-fails.
-
-## Usage
-
-    data-refinery-cli overview
-    data-refinery-cli overview --json
-"""
-
-_DOCTOR = """\
-# data-refinery-cli doctor
-
-Checks the agent-identity invariants `steward doctor` verifies:
-prompt-file-present and backend-consistency (`claude` → `CLAUDE.md`), plus a
-skills-present check. Exits 1 when unhealthy.
-
-## Usage
-
-    data-refinery-cli doctor
-    data-refinery-cli doctor --json
-"""
-
-_CLI = """\
-# data-refinery-cli cli
-
-Noun group for CLI-surface introspection. `cli overview` describes the CLI
-itself (distinct from the global `overview`, which describes the agent).
-
-## Usage
-
-    data-refinery-cli cli overview
-    data-refinery-cli cli overview --json
-"""
-
-
-ENTRIES: dict[tuple[str, ...], str] = {
-    (): _ROOT,
-    ("data-refinery-cli",): _ROOT,
-    ("whoami",): _WHOAMI,
-    ("learn",): _LEARN,
-    ("explain",): _EXPLAIN,
-    ("overview",): _OVERVIEW,
-    ("doctor",): _DOCTOR,
-    ("cli",): _CLI,
-    ("cli", "overview"): _CLI,
-}