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

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

@@ -5,6 +5,24 @@ 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.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.0/CLAUDE.md

@@ -0,0 +1,322 @@
+# 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. (Note the repo description and
+  `pyproject.toml` already say "gaze and expression surface", which is drift to
+  resolve one way or the other.)
+- **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.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: face-cli
+Version: 0.7.0
+Summary: 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 and expression surface for robots, kiosks, and screens.
+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.0/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.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "face-cli"
-version = "0.6.1"
+version = "0.7.0"
 description = "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 and expression surface for robots, kiosks, and screens."
 readme = "README.md"
 license = "Apache-2.0"

{face_cli-0.6.1 → face_cli-0.7.0}/uv.lock

@@ -154,9 +154,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/61/e8/cb8e80d6f9f55b99588625062822bf946cf03ed06315df4bd8397f5632a1/coverage-7.14.0-py3-none-any.whl", hash = "sha256:8de5b61163aee3d05c8a2beab6f47913df7981dad1baf82c414d99158c286ab1", size = 211764, upload-time = "2026-05-10T18:02:29.538Z" },
 ]
 
+[[package]]
+name = "execnet"
+version = "2.1.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/bf/89/780e11f9588d9e7128a3f87788354c7946a9cbb1401ad38a48c4db9a4f07/execnet-2.1.2.tar.gz", hash = "sha256:63d83bfdd9a23e35b9c6a3261412324f964c2ec8dcd8d3c6916ee9373e0befcd", size = 166622, upload-time = "2025-11-12T09:56:37.75Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ab/84/02fc1827e8cdded4aa65baef11296a9bbe595c474f0d6d758af082d849fd/execnet-2.1.2-py3-none-any.whl", hash = "sha256:67fba928dd5a544b783f6056f449e5e3931a5c378b128bc18501f7ea79e296ec", size = 40708, upload-time = "2025-11-12T09:56:36.333Z" },
+]
+
 [[package]]
 name = "face-cli"
-version = "0.6.1"
+version = "0.7.0"
 source = { editable = "." }
 
 [package.dev-dependencies]
@@ -185,15 +194,6 @@ dev = [
     { name = "teken", specifier = ">=0.8" },
 ]
 
-[[package]]
-name = "execnet"
-version = "2.1.2"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/bf/89/780e11f9588d9e7128a3f87788354c7946a9cbb1401ad38a48c4db9a4f07/execnet-2.1.2.tar.gz", hash = "sha256:63d83bfdd9a23e35b9c6a3261412324f964c2ec8dcd8d3c6916ee9373e0befcd", size = 166622, upload-time = "2025-11-12T09:56:37.75Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/ab/84/02fc1827e8cdded4aa65baef11296a9bbe595c474f0d6d758af082d849fd/execnet-2.1.2-py3-none-any.whl", hash = "sha256:67fba928dd5a544b783f6056f449e5e3931a5c378b128bc18501f7ea79e296ec", size = 40708, upload-time = "2025-11-12T09:56:36.333Z" },
-]
-
 [[package]]
 name = "flake8"
 version = "7.3.0"

face_cli-0.6.1/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 **face-cli** agent.
-
-## Description
-
-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 and expression surface for robots, kiosks, and screens.
-
-## 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`, `face-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.

face_cli-0.6.1/PKG-INFO

@@ -1,76 +0,0 @@
-Metadata-Version: 2.4
-Name: face-cli
-Version: 0.6.1
-Summary: 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 and expression surface for robots, kiosks, and screens.
-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 and expression surface for robots, kiosks, and screens.
-
-## What you get
-
-- **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 template runs
-  `backend: colleague`).
-- **The canonical guildmaster skill kit** (11 skills) 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.
-
-## Quickstart
-
-```bash
-uv sync
-uv run pytest -n auto                 # run the test suite
-uv run face-cli whoami  # identity from culture.yaml
-uv run face-cli learn   # self-teaching prompt (add --json)
-uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
-```
-
-## 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.
-
-## Make it your own
-
-1. Rename the package `face_cli/` and the `face-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.
-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
-   [`docs/skill-sources.md`](docs/skill-sources.md)).
-
-See [`CLAUDE.md`](CLAUDE.md) for the full conventions (version-bump-every-PR,
-the `cicd` PR lane, deploy setup).
-
-## License
-
-Apache 2.0 — see [`LICENSE`](LICENSE).

face_cli-0.6.1/README.md

@@ -1,59 +0,0 @@
-# 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 and expression surface for robots, kiosks, and screens.
-
-## What you get
-
-- **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 template runs
-  `backend: colleague`).
-- **The canonical guildmaster skill kit** (11 skills) 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.
-
-## Quickstart
-
-```bash
-uv sync
-uv run pytest -n auto                 # run the test suite
-uv run face-cli whoami  # identity from culture.yaml
-uv run face-cli learn   # self-teaching prompt (add --json)
-uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
-```
-
-## 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.
-
-## Make it your own
-
-1. Rename the package `face_cli/` and the `face-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.
-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
-   [`docs/skill-sources.md`](docs/skill-sources.md)).
-
-See [`CLAUDE.md`](CLAUDE.md) for the full conventions (version-bump-every-PR,
-the `cicd` PR lane, deploy setup).
-
-## License
-
-Apache 2.0 — see [`LICENSE`](LICENSE).