intern-cli 0.4.0__tar.gz → 0.4.1__tar.gz

{intern_cli-0.4.0 → intern_cli-0.4.1}/CHANGELOG.md

@@ -5,6 +5,16 @@ 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.4.1] - 2026-07-18
+
+### Changed
+
+- Replaced the seed-placeholder `CLAUDE.md` with a full runtime guide (via `/init`): documents the three-form name split (dist `intern-cli` / package `intern` / console command `intern`), the CLI dispatch + `register()` pattern, the agent-first output contract, the `culture.yaml`/`doctor` identity model, and the version-bump/PR/skill-vendoring conventions.
+
+### Fixed
+
+- README Quickstart invoked the CLI as `intern-cli whoami`/`intern-cli learn`, but the installed console command is `intern` (dist name `intern-cli` is the PyPI/distribution name only) — those examples failed. Corrected them and added a note clarifying the command vs. dist vs. import-package names; also fixed the rename step to reflect all three forms.
+
 ## [0.4.0] - 2026-06-23
 
 ### Added

intern_cli-0.4.1/CLAUDE.md

@@ -0,0 +1,218 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repo actually is (read first)
+
+`intern-cli` brands itself (in `pyproject.toml`, `README.md`, the package
+description) as *"a small, embeddable agent that wraps the Bonsai 1-bit /
+ternary small language model."* **That is the intended domain, not the current
+code.** There is no inference, model-loading, or Bonsai code in the tree today.
+
+What actually ships is a **clonable agent-first CLI template for an AgentCulture
+mesh agent**: an introspection CLI (`whoami`, `learn`, `explain`, `overview`,
+`doctor`), a mesh identity (`culture.yaml` + a resident prompt file), the
+vendored guildmaster skill kit under `.claude/skills/`, and a build/deploy
+baseline. The `learn`/`explain`/`overview` text describe it literally as
+"a clonable template for AgentCulture mesh agents." When you work here, treat it
+as *that scaffold* — the SLM-wrapping is aspirational until someone builds it.
+
+## The name has three different forms — don't confuse them
+
+| Form | Value | Where it lives |
+|------|-------|----------------|
+| Distribution / PyPI name | `intern-cli` | `pyproject.toml` `name`, wheel, SonarCloud key `agentculture_intern-cli` |
+| Import package | `intern` | the `intern/` directory, `import intern` |
+| **Console command** | **`intern`** | `[project.scripts]` → `intern = "intern.cli:main"` |
+| argparse `prog` (help/usage text) | `intern-cli` | `_build_parser()`, all docstrings, `learn`/`explain` bodies |
+
+**The runnable command is `intern`, NOT `intern-cli`.** The README's
+`uv run intern-cli whoami` examples are aspirational and will fail today —
+the real invocation is `uv run intern whoami`. Every command's *help text*
+still prints `intern-cli` because argparse's `prog` is set to `intern-cli`;
+that mismatch is intentional-looking but is a live gotcha. Verify with
+`uv run intern --version`.
+
+## Common commands
+
+```bash
+uv sync                                   # install deps (creates .venv)
+
+# Run the CLI (command is `intern`, or `python -m intern`)
+uv run intern whoami                      # identity from culture.yaml
+uv run intern learn --json                # self-teaching prompt
+uv run intern doctor                      # agent-identity invariants
+
+# Tests
+uv run pytest -n auto                     # full suite, parallel (pytest-xdist)
+uv run pytest tests/test_cli.py           # one file
+uv run pytest tests/test_cli.py::test_whoami_json   # one test
+uv run pytest -n auto --cov=intern --cov-report=term # with coverage (CI gate: fail_under=60)
+
+# Lint (all four run in CI; run before opening a PR)
+uv run black --check intern tests         # formatter (line-length 100)
+uv run isort --check-only intern tests    # import order (black profile)
+uv run flake8 intern tests
+uv run bandit -c pyproject.toml -r intern
+markdownlint-cli2 "**/*.md" "#.claude/skills"   # markdown (skips vendored skills)
+
+# The agent-first rubric gate — CI's hard gate, 26 checks across 7 bundles
+uv run teken cli doctor . --strict
+```
+
+`black .` / `isort .` (no `--check`) auto-fix. For markdown, use the `lint-fix`
+agent or `markdownlint-cli2 --fix`.
+
+## Architecture
+
+### Dispatch flow
+
+`intern/cli/__init__.py:main(argv)` is the single entry point (returns an
+`int` exit code; the `[project.scripts]` shim and `python -m intern` both call
+it). Flow:
+
+1. `main()` peeks raw argv for `--json` and stashes it on
+   `_CliArgumentParser._json_hint` **before** parsing — so even argparse-level
+   errors (unknown verb, bad flag) honour `--json`.
+2. `_build_parser()` builds the top parser, then calls each command module's
+   `register(sub)` to attach its subparser. Subparsers are built with
+   `parser_class=_CliArgumentParser` so their `.error()` routes through the
+   structured error contract too (not argparse's default stderr + exit 2).
+3. `_dispatch()` calls `args.func(args)`. A handler returns `None`/`int` on
+   success or raises `CliError`. Any *other* exception is caught and wrapped
+   into a `CliError` so **no Python traceback ever leaks to stderr**.
+
+### Adding a command or noun group
+
+Every command module in `intern/cli/_commands/` exposes one function:
+
+```python
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("myverb", help="...")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_myverb)     # cmd_myverb(args) -> int | None
+```
+
+Then add one line in `_build_parser()` (there's a commented example). Handlers
+must import `emit_result`/`emit_error` from `intern.cli._output` and raise
+`CliError` (from `intern.cli._errors`) on failure — never `print()`, never
+`sys.exit()`, never raise a bare exception for an expected error. A **noun
+group** (a subparser with its own sub-verbs, like `cli`) must expose an
+`overview` verb — the rubric's `overview_cli_noun_exists` check requires it, and
+a bare `intern <noun>` should print that overview. See
+`intern/cli/_commands/cli.py` as the template.
+
+If you add a verb/noun, also add a matching entry to `ENTRIES` in
+`intern/explain/catalog.py` — `test_every_catalog_path_resolves` walks every
+catalog key through `explain` and the rubric checks `explain` coverage.
+
+### The agent-first output contract (stable — don't break)
+
+These invariants are enforced by both the pytest suite and `teken cli doctor
+--strict`. Breaking one is a regression even if nothing else fails:
+
+- **stdout = results, stderr = diagnostics/errors — never mixed.**
+  `emit_result` → stdout; `emit_error`/`emit_diagnostic` → stderr.
+- **`--json` on every command.** JSON payloads go to the same split streams.
+  In JSON mode, errors emit `{"code","message","remediation"}` to stderr.
+- **Text errors are two lines:** `error: <message>` then `hint: <remediation>`.
+  The `hint:` prefix is load-bearing (agents grep for it; the rubric checks it).
+- **Exit codes:** `0` success, `1` user-input error, `2` environment/setup
+  error, `3+` reserved. Centralised in `intern/cli/_errors.py`.
+- **Descriptive verbs never hard-fail on a bad target.** `overview <bogus>`
+  exits 0 (it describes *this* agent, ignoring the positional).
+
+### Identity & `doctor`
+
+`culture.yaml` declares the mesh identity — `suffix` (the nick), `backend`, and
+`model`. `whoami.py` parses it **without a YAML dependency** (the runtime has
+zero third-party deps — see `pyproject.toml` `dependencies = []`), reading
+simple `key: value` lines from the first agent block and falling back to
+literals if the shape is unexpected. `find_culture_yaml()` walks up from
+`__file__` (not the CWD) so identity is always the agent's own; a wheel install
+with no `culture.yaml` alongside the package falls back to defaults.
+
+`doctor` mirrors the `steward doctor` invariants: **backend-consistency**
+(the `backend` in `culture.yaml` maps to a required prompt file) plus a
+**skills-present** check. The mapping lives in `doctor.py:_PROMPT_FILE`:
+
+| backend | required prompt file |
+|---------|----------------------|
+| `claude` | `CLAUDE.md` |
+| `colleague` | `AGENTS.colleague.md` |
+| `acp` | `AGENTS.md` |
+| `gemini` | `GEMINI.md` |
+
+**This repo runs `backend: colleague`**, so the invariant-checked resident
+prompt is `AGENTS.colleague.md`. This `CLAUDE.md` is for Claude Code's benefit
+and is *not* what `doctor` validates. If you change `culture.yaml`'s `backend`,
+you must also create the matching prompt file (and teach `doctor` any new
+backend), or `doctor` — and CI — goes red.
+
+## Conventions & workflow
+
+### Version-bump on every PR (CI-enforced)
+
+The `version-check` job in `.github/workflows/tests.yml` fails the PR if
+`pyproject.toml`'s `version` equals `main`'s — **every** PR bumps it, even
+docs/config/CI-only changes. Use the `version-bump` skill (`/version-bump
+patch|minor|major`), which updates `pyproject.toml` and prepends a Keep-a-
+Changelog entry to `CHANGELOG.md`. The runtime `__version__`
+(`intern/__init__.py`) reads from installed package metadata, so it tracks
+`pyproject.toml` automatically — don't hand-edit it.
+
+### PR / CI lane
+
+Use the `cicd` skill for the PR lifecycle (it layers on `devex pr`, adds
+SonarCloud gate + unresolved-thread status via `status`/`await`). Two GitHub
+Actions workflows:
+
+- **`tests.yml`** — `test` (pytest + coverage → SonarCloud when `SONAR_TOKEN`
+  is set), `lint` (black/isort/flake8/bandit/markdownlint + the `teken` rubric
+  gate), and `version-check` (PR-only).
+- **`publish.yml`** — PyPI Trusted Publishing (OIDC, no tokens). PRs that touch
+  `pyproject.toml` or `intern/**` publish a `.devN` build to **TestPyPI**;
+  pushes to `main` publish to **PyPI**. Fork PRs skip publish (no OIDC context).
+
+Follow the standard flow: branch, implement, bump version, open PR via `cicd`,
+address review threads, merge. Sign online posts per the global instructions
+(inside AgentCulture repos the `cicd`/`communicate` scripts sign as
+`- intern-cli (Claude)` automatically — don't hand-sign the body).
+
+### Vendored skills — cite-don't-import
+
+`.claude/skills/` holds ~13 skills vendored verbatim from **guildmaster** (the
+AgentCulture skills supplier); a few originate in `devague`/`colleague` and are
+tracked as divergences. `docs/skill-sources.md` is the authoritative provenance
+ledger and re-sync procedure — **read it before touching any skill.** Rules:
+don't reformat vendored skill bodies (markdownlint and Sonar both exclude
+`.claude/skills/**`); every `SKILL.md` needs `type: command` in its frontmatter
+(load-bearing — `core.skill_loader` silently skips files without it); to update
+a skill, re-vendor from upstream and re-apply only the documented
+identifier-only adaptations rather than editing in place.
+
+Some skills need external CLIs on PATH: `devex` (>=0.21) for `cicd`, `agtag`
+(>=0.1) for `communicate`, `eidetic` for `remember`/`recall`, `colleague`
+(optional) for `ask-colleague`. `.claude/skills.local.yaml.example` documents
+per-machine config (sibling project paths, culture server manifest).
+
+### Renaming this template to mint a new agent
+
+The name is hard-coded in ~100 places across three forms (see the table above).
+Discover every occurrence first, then change deliberately:
+
+```bash
+# Every literal occurrence of the dist name and package name:
+git grep -n -e 'intern-cli' -e '\bintern\b' -- ':!uv.lock'
+git mv intern <newpkg>          # rename the package dir
+```
+
+Touch at least: `pyproject.toml` (`name`, `[project.scripts]`,
+`known_first_party`, `packages`, coverage `source`), `culture.yaml`
+(`suffix`/`backend`/`model`), the package dir + all imports, `tests/`,
+`sonar-project.properties` (`projectKey`), `README.md`, the resident prompt
+file, and — because they're baked into user-facing strings — the `prog=` in
+`_build_parser()`, every docstring, the `learn`/`explain`/`overview` bodies, and
+`whoami._FALLBACK_NICK`. Run `uv run pytest -n auto` and `uv run teken cli
+doctor . --strict` after; the tests assert on the literal strings and will catch
+a missed spot. Then rewrite this `CLAUDE.md` and re-run `/init`.

{intern_cli-0.4.0 → intern_cli-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: intern-cli
-Version: 0.4.0
+Version: 0.4.1
 Summary: A small, embeddable agent that wraps the Bonsai 1-bit / ternary small language model — a lightweight 'intern' you drop into any project as a Small-mode harness component for cheap local inference.
 Project-URL: Homepage, https://github.com/agentculture/intern-cli
 Project-URL: Issues, https://github.com/agentculture/intern-cli/issues
@@ -36,13 +36,17 @@ A small, embeddable agent that wraps the Bonsai 1-bit / ternary small language m
 ```bash
 uv sync
 uv run pytest -n auto                 # run the test suite
-uv run intern-cli whoami  # identity from culture.yaml
-uv run intern-cli learn   # self-teaching prompt (add --json)
+uv run intern whoami                  # identity from culture.yaml
+uv run intern learn                   # self-teaching prompt (add --json)
 uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
 ```
 
 ## CLI
 
+The installed console command is **`intern`** (the `intern-cli` name is the
+distribution/PyPI name; the import package is `intern`). Invoke verbs as
+`intern <verb>` — e.g. `uv run intern whoami`.
+
 | Verb | What it does |
 |------|--------------|
 | `whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
@@ -58,11 +62,12 @@ error, `3+` reserved.
 
 ## Make it your own
 
-1. Rename the package `intern/` and the `intern-cli`
-   CLI/dist name throughout `pyproject.toml`, the package, `tests/`,
-   `sonar-project.properties`, and this `README.md`. The name is hard-coded in
-   ~100 places, so list every occurrence first — see the `git grep` discovery
-   command in [`CLAUDE.md`](CLAUDE.md), the authoritative rename procedure.
+1. Rename the import package `intern/`, the `intern` console command
+   (`[project.scripts]`), and the `intern-cli` dist name throughout
+   `pyproject.toml`, the package, `tests/`, `sonar-project.properties`, and this
+   `README.md`. The names are hard-coded in ~100 places across three forms, so
+   list every occurrence first — see the `git grep` discovery command in
+   [`CLAUDE.md`](CLAUDE.md), the authoritative rename procedure.
 2. Edit `culture.yaml` with your `suffix` and `backend`.
 3. Rewrite `CLAUDE.md` for your agent and run `/init`.
 4. Re-vendor only the skills you need from guildmaster (see

{intern_cli-0.4.0 → intern_cli-0.4.1}/README.md

@@ -19,13 +19,17 @@ A small, embeddable agent that wraps the Bonsai 1-bit / ternary small language m
 ```bash
 uv sync
 uv run pytest -n auto                 # run the test suite
-uv run intern-cli whoami  # identity from culture.yaml
-uv run intern-cli learn   # self-teaching prompt (add --json)
+uv run intern whoami                  # identity from culture.yaml
+uv run intern learn                   # self-teaching prompt (add --json)
 uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
 ```
 
 ## CLI
 
+The installed console command is **`intern`** (the `intern-cli` name is the
+distribution/PyPI name; the import package is `intern`). Invoke verbs as
+`intern <verb>` — e.g. `uv run intern whoami`.
+
 | Verb | What it does |
 |------|--------------|
 | `whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
@@ -41,11 +45,12 @@ error, `3+` reserved.
 
 ## Make it your own
 
-1. Rename the package `intern/` and the `intern-cli`
-   CLI/dist name throughout `pyproject.toml`, the package, `tests/`,
-   `sonar-project.properties`, and this `README.md`. The name is hard-coded in
-   ~100 places, so list every occurrence first — see the `git grep` discovery
-   command in [`CLAUDE.md`](CLAUDE.md), the authoritative rename procedure.
+1. Rename the import package `intern/`, the `intern` console command
+   (`[project.scripts]`), and the `intern-cli` dist name throughout
+   `pyproject.toml`, the package, `tests/`, `sonar-project.properties`, and this
+   `README.md`. The names are hard-coded in ~100 places across three forms, so
+   list every occurrence first — see the `git grep` discovery command in
+   [`CLAUDE.md`](CLAUDE.md), the authoritative rename procedure.
 2. Edit `culture.yaml` with your `suffix` and `backend`.
 3. Rewrite `CLAUDE.md` for your agent and run `/init`.
 4. Re-vendor only the skills you need from guildmaster (see

{intern_cli-0.4.0 → intern_cli-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "intern-cli"
-version = "0.4.0"
+version = "0.4.1"
 description = "A small, embeddable agent that wraps the Bonsai 1-bit / ternary small language model — a lightweight 'intern' you drop into any project as a Small-mode harness component for cheap local inference."
 readme = "README.md"
 license = "Apache-2.0"

{intern_cli-0.4.0 → intern_cli-0.4.1}/uv.lock

@@ -188,7 +188,7 @@ wheels = [
 
 [[package]]
 name = "intern-cli"
-version = "0.4.0"
+version = "0.4.1"
 source = { editable = "." }
 
 [package.dev-dependencies]

intern_cli-0.4.0/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 **intern-cli** agent.
-
-## Description
-
-A small, embeddable agent that wraps the Bonsai 1-bit / ternary small language model — a lightweight 'intern' you drop into any project as a Small-mode harness component for cheap local inference.
-
-## 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`, `intern-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.