face-cli 0.6.1__tar.gz → 0.7.1__tar.gz

{face_cli-0.6.1 → face_cli-0.7.1}/CHANGELOG.md

@@ -5,6 +5,81 @@ 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.7.1] - 2026-07-24
+
+### Added
+
+- **`--json` is accepted before the verb, not only after it** — `face --json
+  whoami` used to fail with `unrecognized arguments: --json` while `face whoami
+  --json` worked. Flag-before-verb is a common idiom, and an agent-first CLI
+  that rejects it is a trap. The root parser now declares `--json`, and
+  `main()` re-asserts it after `parse_args` from the existing raw-argv scan:
+  each subparser re-declares `--json` with its own `False` default, which
+  silently overwrites a leading flag during sub-parsing. Both orders now
+  produce identical output, pinned by a parametrized test.
+- **`face --json` with no verb emits the machine-readable command map** rather
+  than an error — the JSON analogue of printing help. It reuses `learn`'s
+  payload builder (promoted from `_as_json_payload` to `as_json_payload`), so
+  there is one command map, not two.
+
+### Changed
+
+- **The CLI's own introspection text now describes this agent** — `face --help`,
+  `face learn`, `face explain`, and `face overview` still called the repo "a
+  clonable template for AgentCulture mesh agents" and gave clone/rename
+  instructions, contradicting the docs 0.7.0 rewrote. Because `learn` and
+  `explain` are explicitly the machine-readable teaching surface, that mismatch
+  misinformed every agent consuming them, not just human readers. All four now
+  state the domain (the expressive output side of a face; recognition belongs to
+  the sibling) and the honest status (scaffold — no renderer, no gaze primitive,
+  no render verbs yet), and `overview` gained a `Status` section carrying the
+  same. The leftover clone/rename framing is also gone from the `whoami` and
+  `overview` module docstrings. The `face` / `face-cli` naming split is
+  untouched: the console script stays `face` and every help / `learn` /
+  `explain` string stays `face-cli`, matching argparse's `prog`.
+- **Package metadata no longer advertises capability that was never requested**
+  — `pyproject.toml`'s description promised a "gaze **and expression** surface"
+  while `README.md` says "gaze surface" and the build brief records that
+  expression was *not* asked for. Published metadata is public-facing (it is
+  what PyPI shows), so the conflicting claim was narrowed to match the README.
+  This removes the claim rather than settling the scope question, which stays
+  open in `CLAUDE.md`; the GitHub repo description, set at provisioning, still
+  carries the old wording and should follow whichever way the decision lands.
+
+- **Public-facing descriptions no longer read as if the renderer exists** —
+  `pyproject.toml`'s description (what PyPI renders, and `publish.yml` pushes a
+  release on every merge to `main`) and the root `argparse` description both
+  described a working browser-rendered face in the present tense, while
+  `learn` / `explain` / `overview` said "scaffold, no renderer". Both now carry
+  the same qualifier. This also makes 0.7.1's own claim about `face --help`
+  true — it stated the honest status was there before the root description
+  actually carried it.
+
+The first two items were raised by Qodo's review of
+[#2](https://github.com/agentculture/face-cli/pull/2) (review comments
+`3646920415`, `3646920422`), which merged before the fixes landed — hence a
+follow-up release rather than an amendment. The remaining items came from
+Qodo's review of [#3](https://github.com/agentculture/face-cli/pull/3) (review
+comments `3647009663`, `3647009668`).
+
+## [0.7.0] - 2026-07-24
+
+### Added
+
+- **`CLAUDE.md` initialized from the seed** (`/init`) — replaces the bootstrap placeholder with a real runtime prompt: what the repo is *today* (a scaffold, no renderer on disk), the deliberate `face` command / `face_cli` import / `face-cli` dist split and why it must not be "fixed", the four CLI contracts the rubric gate enforces (registration via `register(sub)`, the `CliError` + `_json_hint` error path, the strict stdout/stderr split, the tuple-keyed `explain` catalog), the five places a new verb must touch, and the decided-vs-open state of the face work carried over from build brief agentculture/face-cli#1.
+- **Face-recognition acceptance constraint** recorded in `CLAUDE.md` and `README.md` — the rendered face must survive the same OpenCV pipeline sibling `face-recognition-cli` extracts from `reachy-mini-cli` (`reachy/vision/face.py`): YuNet detection above the default `0.6` score threshold, and a stable SFace 128-dim embedding across the gaze range. This settles the brief's stylised-vs-realistic question at "realistic enough that a detector fires" rather than photorealism, and replaces the untestable "it looks 3D" with an assertion CI can make — a face that stops being detectable at extreme yaw has failed the illusion in a way a screenshot diff would miss.
+- **Dependency guidance for when the renderer lands** — the empty runtime-dependency set is a property of the scaffold, not a law: put a server/screenshot stack behind an extra, import it lazily inside functions, and surface absence as a clean `EXIT_ENV_ERROR` `CliError`, mirroring `reachy-mini-cli`'s `[vision]` pattern.
+- **Template conventions restored** into `CLAUDE.md` after the scaffold flattened them — version-bump-every-PR, the `cicd` PR lane, the `ask-colleague` reflex, verbatim-vendored skills, the `../.worktrees.face-cli/<name>/` worktree convention, and in-repo public memory discipline (`/recall` before, `/remember` after).
+
+### Changed
+
+- **`README.md` rewritten for this agent** — it described the `culture-agent-template` clone procedure ("Make it your own", the ~100-place rename sweep) rather than face-cli. Now leads with the scaffold status, the two halves of the problem (depth illusion + pointable gaze), the decided browser render target with its three reasons, the face-recognition bar, and the lane boundary against `face-recognition-cli`.
+
+### Fixed
+
+- **Wrong console command throughout `README.md`** — the quickstart said `uv run face-cli whoami` / `uv run face-cli learn`, which fail with `Failed to spawn: face-cli`. The installed entry point is `face` (`[project.scripts] face = "face_cli.cli:main"`); only argparse's `prog` is `face-cli`.
+- **Stale identity claim in the seed** — it stated `culture.yaml` declares `backend: claude`, while the checked-in value is `colleague` (resident prompt `AGENTS.colleague.md`, which is what `doctor` and `steward doctor` actually verify).
+
 ## [0.6.1] - 2026-07-20
 
 ### Added

face_cli-0.7.1/CLAUDE.md

@@ -0,0 +1,325 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this project is
+
+`face-cli` is the **expressive output side of a face**: a simulated face
+rendered in the browser that reads as three-dimensional on a flat 2D screen and
+can look in any direction — an agent-drivable gaze surface for robots, kiosks,
+and screens.
+
+**Status on disk today: scaffold only.** There is no renderer, no browser
+asset, no gaze primitive, and no `serve` verb in this repo yet. What exists is
+the `culture-agent-template` baseline — an agent-first CLI skeleton, a mesh
+identity, the vendored skill kit, and CI. *The face is the work, and it has not
+started.* Keep that distinction visible when you write docs: describe the repo
+as it is, and mark anything else `(planned)` or put it under a roadmap heading.
+
+The authoritative statement of the lane is the build brief,
+[agentculture/face-cli#1](https://github.com/agentculture/face-cli/issues/1).
+Read it before designing anything. This file summarizes the parts that are
+already decided and the parts that are still open; the issue is the source of
+truth and the place to renegotiate.
+
+## Naming — deliberately decoupled, do not "fix"
+
+| Thing | Value |
+|---|---|
+| Console command | `face` |
+| Import package | `face_cli` |
+| PyPI distribution | `face-cli` |
+| Argparse `prog` | `face-cli` |
+
+The command is `face` but the import package is `face_cli` because a bare
+`face` is a real published PyPI distribution (a `glom` dependency) — squatting
+that top-level import would shadow it. This mismatch is intentional; leave it.
+
+Practical consequence: the installed entry point is **`uv run face …`**, not
+`uv run face-cli …`. The help text and `explain` catalog say `face-cli`
+(the `prog`), and `explain` accepts both `face` and `face-cli` as the root key.
+
+## Commands
+
+```bash
+uv sync                                  # create/refresh .venv from uv.lock
+uv run pytest -n auto                    # full suite (xdist, ~22 tests, <1s)
+uv run pytest tests/test_cli.py::test_whoami_json -v   # a single test
+uv run pytest -n auto --cov=face_cli --cov-report=term # coverage (fail_under = 60)
+uv run face whoami                       # identity from culture.yaml
+uv run face learn --json                 # self-teaching prompt
+uv run teken cli doctor . --strict       # the agent-first rubric gate CI runs
+```
+
+Lint — CI runs all five and any one failing fails the `lint` job:
+
+```bash
+uv run black --check face_cli tests      # line-length 100
+uv run isort --check-only face_cli tests
+uv run flake8 face_cli tests
+uv run bandit -c pyproject.toml -r face_cli
+markdownlint-cli2 "**/*.md" "#node_modules" "#.local" "#.claude/skills" "#.teken"
+```
+
+Version bump (required on every PR — see Conventions):
+
+```bash
+python3 .claude/skills/version-bump/scripts/bump.py patch|minor|major
+```
+
+## Architecture — the CLI as it stands
+
+The whole CLI is cited (cite-don't-import) from teken's `python-cli` reference,
+which is why **the runtime package has zero third-party dependencies**;
+`teken` is a dev dependency only. Four contracts hold it together, and the
+rubric gate (`teken cli doctor . --strict`, 26 checks) enforces all of them:
+
+- **Registration.** `face_cli/cli/__init__.py::_build_parser` imports each
+  module under `cli/_commands/` and calls its `register(sub)`. Every command
+  module owns its own parser, flags, and `set_defaults(func=…)`. Adding a verb
+  never touches the dispatcher.
+- **Errors.** Every failure raises `CliError(code, message, remediation)`
+  (`cli/_errors.py`). `_dispatch` catches it, and wraps *any* other exception
+  into one, so a Python traceback can never reach stderr. `_CliArgumentParser`
+  overrides `argparse`'s `.error()` so parse failures take the same path and
+  exit `1` rather than argparse's default `2`. Because parse errors happen
+  before `args.json` exists, `main()` pre-scans raw argv for `--json` and
+  stashes it in the class-level `_json_hint` — that is why the flag is peeked
+  at twice, and it is load-bearing.
+- **Streams.** `cli/_output.py` is the only writer: results to stdout,
+  errors and diagnostics to stderr, never mixed, in both text and JSON mode.
+- **Explain.** `face_cli/explain/catalog.py` maps command-path *tuples* to
+  verbatim markdown. `tests/test_cli.py::test_every_catalog_path_resolves`
+  walks every key, so an entry that exists must resolve; the rubric separately
+  requires an entry for the root and a non-zero exit for a bogus path.
+
+Two modules encode mesh identity rather than CLI mechanics:
+
+- `cli/_commands/whoami.py` walks up from `__file__` (**not** the CWD) to find
+  this agent's own `culture.yaml`, and hand-parses the first agent block
+  without a YAML dependency — that is what keeps runtime deps empty. A wheel
+  install ships no `culture.yaml`, so it falls back to literal defaults.
+- `cli/_commands/doctor.py` mirrors the two invariants `steward doctor`
+  verifies — prompt-file-present and backend-consistency — via the
+  `_PROMPT_FILE` map (`claude` → `CLAUDE.md`, `colleague` →
+  `AGENTS.colleague.md`, `acp` → `AGENTS.md`, `gemini` → `GEMINI.md`), plus a
+  skills-present check. It returns the rubric's
+  `{healthy, checks: [{id, passed, severity, message, remediation}]}` shape.
+
+### Adding a verb or noun group
+
+Five places, and the tests will catch you if you miss one:
+
+1. A module in `face_cli/cli/_commands/` exposing `register(sub)`; add
+   `--json` to every parser you create.
+2. A `register()` call in `_build_parser()`.
+3. An entry in `face_cli/explain/catalog.py` keyed by the path tuple.
+4. The command map inside `cli/_commands/learn.py` — both `_TEXT` and
+   `_as_json_payload()`. The rubric greps `learn` output for markers.
+5. Tests in `tests/`.
+
+Any noun group that gains action verbs must also expose `overview`
+(`overview_cli_noun_exists`); descriptive verbs must not hard-fail on a bad
+target path (`overview_graceful_on_bad_path` — see the ignored `target`
+positional in `overview.py`).
+
+### When the renderer lands
+
+The empty-runtime-deps property is a feature of the scaffold, not a law of the
+project — a browser renderer will need a server and screenshot tooling. Follow
+the sibling pattern instead of adding hard top-level deps: put them behind an
+extra (`[serve]`, `[vision]`), import them **lazily inside functions**, and
+surface a missing dependency as a clean `CliError` with `EXIT_ENV_ERROR` (2)
+pointing at the extra. `reachy-mini-cli`'s `reachy/vision/face.py` is the
+reference implementation of that pattern in this workspace.
+
+## The face work — what is decided
+
+**The render target is the browser.** Decided by the operator; hold the line
+when it gets inconvenient. Three reasons, all still true: no display server is
+needed on a headless robot box or server; the screen showing the face need not
+be the machine running the process; and a page can be screenshotted and diffed
+in CI, which a native window effectively cannot. WebGL vs 2D canvas vs SVG is
+an open technique choice — the operator specified the target, not the method.
+
+**The rendered face must survive face recognition.** This is an operator
+requirement layered on the brief: our virtual face should be recognizable *as a
+face, and as a consistent identity*, by the same machinery that recognizes real
+people. The concrete pipeline is the sibling `face-recognition-cli`'s, which
+extracts `reachy-mini-cli`'s OpenCV engine (`reachy/vision/face.py`):
+
+- **YuNet** (`face_detection_yunet_2023mar.onnx`) for detection — default
+  score threshold `0.6`, NMS `0.3`, `320x320` input, largest-face selection.
+- **SFace** (`face_recognition_sface_2021dec.onnx`) for a 128-dim embedding,
+  taken after `alignCrop` on YuNet's five landmarks.
+
+That has three consequences worth holding onto:
+
+1. It effectively answers the brief's stylised-vs-realistic question. A face
+   abstract enough to be two floating eyes will not fire a YuNet detection at
+   `0.6`. The render needs the landmark geometry YuNet regresses — two eyes, a
+   nose tip, two mouth corners — in plausible proportion, with enough tonal
+   contrast to survive `alignCrop`. It does not need photorealism, and chasing
+   photorealism buys the uncanny valley; "passes a detector" is a much cheaper
+   and much more testable bar than "looks real".
+2. It replaces "it looks 3D" with an assertion CI can actually make. Render at
+   a known gaze angle → YuNet detects exactly one face above threshold →
+   SFace's embedding stays cosine-close to an enrolled reference across the
+   whole gaze range. That gates *both* halves of the brief at once: a face that
+   stops being detectable at ±40° yaw has failed the 3D illusion in a way a
+   screenshot diff would not have caught.
+3. It defines the composition with the sibling without merging the lanes.
+   `face-cli` renders; `face-recognition-cli` enrolls and matches; the loop
+   closes when the same identity comes back. That integration is explicit and
+   coordinated through issues (use the `communicate` skill), not a merge —
+   this repo does no recognition, and that one does no rendering. Note the
+   sibling is *also* a bare scaffold today, so the near-term testable path is
+   OpenCV's YuNet/SFace directly, behind an extra, with the sibling adopted as
+   soon as it has a surface.
+
+### Lane boundaries with siblings
+
+- `face-recognition-cli` — perception (identifies real people from frames).
+  Shares the subject, nothing else.
+- `reachy-mini-cli` — a physical head that actually turns; the on-screen
+  counterpart to this. Plausible that a Reachy gets its face from here; agree
+  it with that agent rather than assuming.
+- `storybook-cli` — also renders to a browser, but its output is a *document*;
+  this one is a *live surface*.
+- `reterminal-cli` — e-paper; its refresh rate is hostile to continuous gaze.
+  Not a first target.
+
+## The face work — what is still open
+
+Decide these deliberately and **record the decision** (a `docs/` note plus a
+CHANGELOG entry); do not let them get settled by accident in a commit:
+
+- **How a one-shot CLI call moves an already-rendered face.** Served page plus
+  a control channel (websocket / SSE / polled state file), a state file the
+  page watches, or something else.
+- **Whether there is a `serve` verb** that owns the page, with `look` /
+  `express` driving it — and what happens when nothing is serving: error, or
+  autostart.
+- **The gaze primitive.** Yaw/pitch degrees, a normalized direction vector, a
+  screen-space point, or a named target. Whatever it is, an agent must be able
+  to compute it with no human in the loop.
+- **Whether expression is in scope at all.** The operator asked for direction.
+  Expression is the obvious neighbour and was *not* requested — decide
+  explicitly rather than drifting into it. Published metadata no longer
+  pre-answers it: `pyproject.toml` used to advertise a "gaze **and expression**
+  surface" while nothing of the sort exists, so its description was narrowed to
+  match the README. That removes the claim, it does not settle the question —
+  the GitHub repo description (set at provisioning) still carries the old
+  wording and should follow whichever way the decision lands.
+- **What `--json` returns for a verb whose real output is pixels.** A
+  screenshot path is one honest answer; the resolved gaze state is another.
+- **Who runs the render loop** — browser-side animation with the CLI setting
+  targets (almost certainly right) or process-side frame pushing.
+- **One face or many** per host.
+- **Pre-rendered assets and their licence**, if any ship. A public repo with
+  vendored face art needs that answer before the first release.
+
+The path for deciding them is the vendored workflow chain: `/scope` → `/think`
+→ `/challenge` → `/spec-to-plan`, then `/assign-to-workforce` if the plan wants
+parallel lanes.
+
+## Identity
+
+```yaml
+agents:
+- suffix: face-cli
+  backend: colleague
+  model: sakamakismile/Qwen3.6-27B-Text-NVFP4-MTP
+```
+
+`backend: colleague` fixes the resident prompt file to **`AGENTS.colleague.md`**
+— the mesh runtime reads that file, while this `CLAUDE.md` is the Claude Code
+guidance file. Both `steward doctor` and `face doctor` check the pair, and it
+currently passes. (The scaffold seed this file replaced claimed
+`backend: claude`; that was wrong — the checked-in value is `colleague`.) The
+build brief asks that `culture.yaml` be reconciled against the backend actually
+run; if this agent is promoted to `claude`, flipping the `backend` value is the
+whole change — `doctor` already maps `claude` → `CLAUDE.md`, but
+`tests/test_cli.py` asserts `backend: colleague` in two places and would need
+updating with it.
+
+## Conventions and workflow
+
+- **Every PR bumps the version** — even docs/config/CI-only PRs. Use the
+  `version-bump` skill; the `version-check` CI job blocks merge otherwise, and
+  the bump script leaves the CHANGELOG sections blank, so write a real entry.
+- **PRs go through the `cicd` skill** (`devex pr` + SonarCloud gating). Sign
+  online posts as `- face-cli (Claude)`; the `cicd` / `communicate` scripts
+  resolve that nick from `culture.yaml` automatically, so do not hand-sign in
+  bodies those scripts author.
+- **Reach for `ask-colleague` reflexively.** Its value is a *second,
+  independent mind* (a different backend/model), not a stronger one. Before
+  presenting or opening a PR on a non-trivial committed diff, run `review`; for
+  a fresh read of an unfamiliar area, run `explore`. Both are read-only in a
+  throwaway worktree, so the reflex is always safe. `write --apply` / `--pr`
+  needs the user's go-ahead. Treat its output as an opinion to verify and own.
+- **The vendored `.claude/skills/` are cited verbatim** — do not reformat or
+  edit their scripts. Re-sync from guildmaster (or the tracked direct-from-origin
+  exceptions) per `docs/skill-sources.md`. Prerequisites on PATH: `devex`
+  (>=0.21) and `agtag` (>=0.1); `colleague` is optional.
+- **Deploy**: pushing to `main` publishes to PyPI via Trusted Publishing;
+  PRs do a TestPyPI dry-run. Both jobs only fire on changes to `pyproject.toml`
+  or `face_cli/**`. A PyPI / TestPyPI Trusted Publisher must be registered for
+  `face-cli` before the first real release — `guild create` configured the
+  GitHub side only.
+
+### Worktrees
+
+Every worktree you create by hand lives in one repo-named directory beside the
+checkout, one subfolder per worktree:
+
+```bash
+git worktree add ../.worktrees.face-cli/<name> -b <branch>
+```
+
+Never a shared `../worktrees/`: this workspace holds ~150 sibling projects, and
+a generic shared folder accumulates orphaned trees from several repos at once
+with nothing indicating ownership — a stale-tree sweep cannot tell a live lane
+from junk. Scope the branch prefix to the work (`gaze/t2`, not `agent/t2`);
+plain `agent/*` collides with leftovers from earlier fan-outs and `git worktree
+add -b` fails on an existing branch. The vendored `assign-to-workforce` skill's
+fan-out example uses *both* the shared path and `agent/<task-id>` branches —
+it is cited verbatim and must not be edited, so override both when following
+it. Remove with `git worktree remove <path>` (which deletes the directory);
+`git worktree prune` only clears metadata for directories already gone. Never
+`rm -rf` a worktree you did not create. Exception: `ask-colleague`'s read-only
+verbs create their own detached worktree under `${TMPDIR:-/tmp}` and reap it on
+an EXIT trap — outside this rule, not a violation of it.
+
+### Memory discipline — recall before, remember after
+
+This repo keeps its eidetic memory **in-repo and public**: a plain `/remember`
+resolves to `<repo-root>/.eidetic/memory` — committed, shared with the team and
+mesh peers, with the `claude` and `colleague` backends reading the same
+`face-cli` scope. So memory travels with the repo rather than a private
+home-dir store.
+
+- **`/recall` before you start** a non-trivial task — prior decisions, gotchas,
+  "have we done this before?" — so you build on what is known.
+- **`/remember` when something worth keeping surfaces**: a non-obvious decision
+  and its rationale, a constraint, a fix and *why*, a gotcha that cost time.
+  Capture it as it happens.
+
+Pass `--visibility private` to keep a record out of the committed store (it
+routes to `$HOME/.eidetic/memory`); `/recall` reads both and merges. Do not
+store what the repo already records — code structure, git history, or anything
+already in this file or `CHANGELOG.md`.
+
+## Layout
+
+```text
+face_cli/                 agent-first CLI (cited from teken's python-cli reference)
+  cli/                    parser, error/output contract, _commands/ (verbs)
+  explain/                markdown catalog for `explain`
+tests/                    pytest smoke + introspection tests
+.claude/skills/           vendored guildmaster/devague/colleague skill kit (verbatim)
+docs/skill-sources.md     skill provenance ledger + re-sync procedure
+culture.yaml              mesh identity (suffix + backend)
+AGENTS.colleague.md       resident prompt for the colleague backend
+.github/workflows/        tests + lint + version-check; PyPI Trusted Publishing
+```

face_cli-0.7.1/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: face-cli
+Version: 0.7.1
+Summary: Scaffold for a browser-rendered face that reads three-dimensional on a flat 2D screen and looks in any direction — an agent-drivable gaze surface for robots, kiosks, and screens. The renderer is not implemented yet; the CLI ships introspection verbs only.
+Project-URL: Homepage, https://github.com/agentculture/face-cli
+Project-URL: Issues, https://github.com/agentculture/face-cli/issues
+Author: AgentCulture
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# face-cli
+
+A simulated face rendered in the browser that appears three-dimensional on a
+flat 2D screen and can look in any direction — an agent-drivable gaze surface
+for robots, kiosks, and screens.
+
+> **Status: scaffold.** The renderer does not exist yet. What ships today is
+> the agent-first CLI baseline, the mesh identity, and CI. The face itself is
+> being designed in the open — see [the build brief][brief] and
+> [`CLAUDE.md`](CLAUDE.md).
+
+[brief]: https://github.com/agentculture/face-cli/issues/1
+
+## The idea
+
+Two halves, and both are the interesting part: the **illusion of depth** on a
+flat surface, and a **gaze that can be pointed anywhere** and reads as pointed
+there. Everything else is in service of those.
+
+`face-cli` is the *expressive output* side of a face. Its sibling
+[`face-recognition-cli`](https://github.com/agentculture/face-recognition-cli)
+is the *perceptual input* side — it identifies real people from camera frames.
+They share a subject and nothing else.
+
+## Decided so far
+
+- **The render target is the browser** — a local page driven over
+  canvas/WebGL/SVG. It needs no display server (so it runs on a headless robot
+  box), the screen showing the face need not be the machine running the
+  process, and a page can be screenshotted and diffed in CI. The *technique*
+  within the browser is still open.
+- **The rendered face must survive face recognition.** Not photorealism — a
+  detector-passing bar: OpenCV **YuNet** should detect it above the standard
+  `0.6` score threshold, and **SFace**'s 128-dim embedding should stay stable
+  across the whole gaze range. That turns "it looks 3D" into an assertion CI
+  can actually make, and it is the seam along which this repo composes with
+  `face-recognition-cli`.
+
+Open questions — the gaze primitive, the control channel between a one-shot CLI
+call and a live page, whether expression is in scope, one face or many — are
+tracked in [`CLAUDE.md`](CLAUDE.md) and [the brief][brief].
+
+## Quickstart
+
+```bash
+uv sync
+uv run pytest -n auto                 # run the test suite
+uv run face whoami                    # identity from culture.yaml
+uv run face learn                     # self-teaching prompt (add --json)
+uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
+```
+
+The console command is **`face`**; the import package is `face_cli` and the
+PyPI distribution is `face-cli`. The mismatch is deliberate — a bare `face` is
+already a published distribution on PyPI, so squatting that import would shadow
+it.
+
+## CLI
+
+| Verb | What it does |
+|------|--------------|
+| `whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
+| `learn` | Print a structured self-teaching prompt. |
+| `explain <path>` | Markdown docs for any noun/verb path. |
+| `overview` | Read-only descriptive snapshot of the agent. |
+| `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
+| `cli overview` | Describe the CLI surface itself. |
+
+Every command supports `--json`. Results go to stdout, errors/diagnostics to
+stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
+error, `3+` reserved.
+
+No gaze or render verbs exist yet — the list above is the scaffold's
+introspection surface.
+
+## What's in the box
+
+- **An agent-first CLI** cited from [teken](https://github.com/agentculture/teken)
+  (`afi-cli`) — the runtime package has no third-party dependencies.
+- **A mesh identity** — `culture.yaml` (`suffix` + `backend`) and the matching
+  resident prompt file (`AGENTS.colleague.md`, since this agent runs
+  `backend: colleague`).
+- **The canonical guildmaster skill kit** under `.claude/skills/`, vendored
+  cite-don't-import. See [`docs/skill-sources.md`](docs/skill-sources.md).
+- **A build + deploy baseline** — pytest, lint, the agent-first rubric gate, and
+  PyPI Trusted Publishing wired into GitHub Actions.
+
+## Contributing
+
+Every PR bumps the version (`version-check` CI blocks merge otherwise) and adds
+a real CHANGELOG entry. See [`CLAUDE.md`](CLAUDE.md) for the full conventions —
+the `cicd` PR lane, worktree layout, and deploy setup.
+
+## License
+
+Apache 2.0 — see [`LICENSE`](LICENSE).

face_cli-0.7.1/README.md

@@ -0,0 +1,96 @@
+# face-cli
+
+A simulated face rendered in the browser that appears three-dimensional on a
+flat 2D screen and can look in any direction — an agent-drivable gaze surface
+for robots, kiosks, and screens.
+
+> **Status: scaffold.** The renderer does not exist yet. What ships today is
+> the agent-first CLI baseline, the mesh identity, and CI. The face itself is
+> being designed in the open — see [the build brief][brief] and
+> [`CLAUDE.md`](CLAUDE.md).
+
+[brief]: https://github.com/agentculture/face-cli/issues/1
+
+## The idea
+
+Two halves, and both are the interesting part: the **illusion of depth** on a
+flat surface, and a **gaze that can be pointed anywhere** and reads as pointed
+there. Everything else is in service of those.
+
+`face-cli` is the *expressive output* side of a face. Its sibling
+[`face-recognition-cli`](https://github.com/agentculture/face-recognition-cli)
+is the *perceptual input* side — it identifies real people from camera frames.
+They share a subject and nothing else.
+
+## Decided so far
+
+- **The render target is the browser** — a local page driven over
+  canvas/WebGL/SVG. It needs no display server (so it runs on a headless robot
+  box), the screen showing the face need not be the machine running the
+  process, and a page can be screenshotted and diffed in CI. The *technique*
+  within the browser is still open.
+- **The rendered face must survive face recognition.** Not photorealism — a
+  detector-passing bar: OpenCV **YuNet** should detect it above the standard
+  `0.6` score threshold, and **SFace**'s 128-dim embedding should stay stable
+  across the whole gaze range. That turns "it looks 3D" into an assertion CI
+  can actually make, and it is the seam along which this repo composes with
+  `face-recognition-cli`.
+
+Open questions — the gaze primitive, the control channel between a one-shot CLI
+call and a live page, whether expression is in scope, one face or many — are
+tracked in [`CLAUDE.md`](CLAUDE.md) and [the brief][brief].
+
+## Quickstart
+
+```bash
+uv sync
+uv run pytest -n auto                 # run the test suite
+uv run face whoami                    # identity from culture.yaml
+uv run face learn                     # self-teaching prompt (add --json)
+uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
+```
+
+The console command is **`face`**; the import package is `face_cli` and the
+PyPI distribution is `face-cli`. The mismatch is deliberate — a bare `face` is
+already a published distribution on PyPI, so squatting that import would shadow
+it.
+
+## CLI
+
+| Verb | What it does |
+|------|--------------|
+| `whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
+| `learn` | Print a structured self-teaching prompt. |
+| `explain <path>` | Markdown docs for any noun/verb path. |
+| `overview` | Read-only descriptive snapshot of the agent. |
+| `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
+| `cli overview` | Describe the CLI surface itself. |
+
+Every command supports `--json`. Results go to stdout, errors/diagnostics to
+stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
+error, `3+` reserved.
+
+No gaze or render verbs exist yet — the list above is the scaffold's
+introspection surface.
+
+## What's in the box
+
+- **An agent-first CLI** cited from [teken](https://github.com/agentculture/teken)
+  (`afi-cli`) — the runtime package has no third-party dependencies.
+- **A mesh identity** — `culture.yaml` (`suffix` + `backend`) and the matching
+  resident prompt file (`AGENTS.colleague.md`, since this agent runs
+  `backend: colleague`).
+- **The canonical guildmaster skill kit** under `.claude/skills/`, vendored
+  cite-don't-import. See [`docs/skill-sources.md`](docs/skill-sources.md).
+- **A build + deploy baseline** — pytest, lint, the agent-first rubric gate, and
+  PyPI Trusted Publishing wired into GitHub Actions.
+
+## Contributing
+
+Every PR bumps the version (`version-check` CI blocks merge otherwise) and adds
+a real CHANGELOG entry. See [`CLAUDE.md`](CLAUDE.md) for the full conventions —
+the `cicd` PR lane, worktree layout, and deploy setup.
+
+## License
+
+Apache 2.0 — see [`LICENSE`](LICENSE).

{face_cli-0.6.1 → face_cli-0.7.1}/face_cli/cli/__init__.py

@@ -26,7 +26,7 @@ import sys
 
 from face_cli import __version__
 from face_cli.cli._errors import EXIT_USER_ERROR, CliError
-from face_cli.cli._output import emit_error
+from face_cli.cli._output import emit_error, emit_result
 
 _ISSUES_URL = "https://github.com/agentculture/face-cli/issues"
 
@@ -71,13 +71,23 @@ def _build_parser() -> argparse.ArgumentParser:
 
     parser = _CliArgumentParser(
         prog="face-cli",
-        description="face-cli — a clonable template for AgentCulture mesh agents.",
+        description="face-cli — a browser-rendered face that reads 3D on a 2D screen "
+        "and looks in any direction. Scaffold: no renderer or gaze verbs yet; the "
+        "verbs below are the introspection surface.",
     )
     parser.add_argument(
         "--version",
         action="version",
         version=f"%(prog)s {__version__}",
     )
+    # Accepted before the verb too (`face --json whoami`), not just after it.
+    # argparse gives each subparser its own `json` default, so a leading flag is
+    # clobbered on the way down; main() re-asserts it from the raw-argv scan.
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Emit structured JSON. Accepted before or after the verb.",
+    )
     # parser_class propagates to every subparser so their .error() routes
     # through _CliArgumentParser too.
     sub = parser.add_subparsers(dest="command", parser_class=_CliArgumentParser)
@@ -125,7 +135,21 @@ def main(argv: list[str] | None = None) -> int:
     parser = _build_parser()
     args = parser.parse_args(argv)
 
+    # Position must not change meaning: each subparser re-declares `--json` with
+    # its own `False` default, which overwrites a leading `--json` during
+    # sub-parsing. Re-assert from the raw-argv scan so `face --json whoami` and
+    # `face whoami --json` behave identically.
+    if _CliArgumentParser._json_hint:
+        args.json = True
+
     if args.command is None:
+        # No verb: the JSON analogue of printing help is the machine-readable
+        # command map, which `learn` already owns.
+        if getattr(args, "json", False):
+            from face_cli.cli._commands.learn import as_json_payload
+
+            emit_result(as_json_payload(), json_mode=True)
+            return 0
         parser.print_help()
         return 0