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

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

@@ -5,6 +5,63 @@ 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

{face_cli-0.7.0 → face_cli-0.7.1}/CLAUDE.md

@@ -205,9 +205,12 @@ CHANGELOG entry); do not let them get settled by accident in a commit:
   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.)
+  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

{face_cli-0.7.0 → face_cli-0.7.1}/PKG-INFO

@@ -1,7 +1,7 @@
 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.
+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

{face_cli-0.7.0 → 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
 

{face_cli-0.7.0 → face_cli-0.7.1}/face_cli/cli/_commands/learn.py

@@ -12,14 +12,19 @@ from face_cli import __version__
 from face_cli.cli._output import emit_result
 
 _TEXT = """\
-face-cli — a clonable template for AgentCulture mesh agents.
+face-cli — a browser-rendered face that reads 3D on a 2D screen and looks
+anywhere.
 
 Purpose
 -------
-Scaffold for a new Culture mesh agent: an agent-first CLI (cited from the teken
-`python-cli` reference), an identity (culture.yaml + CLAUDE.md), the canonical
-guildmaster skill kit under .claude/skills/, and a deploy/CI baseline. Clone it,
-rename the package, and edit culture.yaml to mint a new agent.
+The expressive *output* side of a face: a simulated face rendered in a browser
+that appears three-dimensional on a flat screen and can point its gaze in any
+direction, drivable by an agent. Its sibling face-recognition-cli is the
+perceptual *input* side; this tool does no recognition.
+
+Status: scaffold. No renderer, no gaze primitive, and no render verbs exist
+yet — the commands below are the introspection surface only. See the build
+brief at https://github.com/agentculture/face-cli/issues/1.
 
 Commands
 --------
@@ -48,11 +53,15 @@ More detail
 """
 
 
-def _as_json_payload() -> dict[str, object]:
+def as_json_payload() -> dict[str, object]:
+    """Machine-readable command map. Shared with the root `--json` (no verb) path."""
     return {
         "tool": "face-cli",
         "version": __version__,
-        "purpose": "Clonable scaffold for a new AgentCulture mesh agent.",
+        "purpose": (
+            "Browser-rendered face that reads 3D on a 2D screen and looks in any "
+            "direction. Scaffold: no render verbs yet."
+        ),
         "commands": [
             {"path": ["whoami"], "summary": "Identity probe from culture.yaml."},
             {"path": ["learn"], "summary": "Self-teaching prompt."},
@@ -73,7 +82,7 @@ def _as_json_payload() -> dict[str, object]:
 
 def cmd_learn(args: argparse.Namespace) -> int:
     if getattr(args, "json", False):
-        emit_result(_as_json_payload(), json_mode=True)
+        emit_result(as_json_payload(), json_mode=True)
     else:
         emit_result(_TEXT, json_mode=False)
     return 0

{face_cli-0.7.0 → face_cli-0.7.1}/face_cli/cli/_commands/overview.py

@@ -1,7 +1,7 @@
 """``face-cli overview`` — read-only descriptive snapshot of the agent.
 
 Describes the agent to an agent reader: identity (from culture.yaml), the verb
-surface, and the sibling-pattern artifacts this template carries. The shared
+surface, and the sibling-pattern artifacts this repo carries. The shared
 section/render helpers here are reused by the ``cli`` noun's ``overview`` (see
 :mod:`face_cli.cli._commands.cli`).
 
@@ -24,6 +24,13 @@ _ARTIFACTS = [
     "pyproject.toml + .github/workflows/ — buildable, deployable package baseline",
 ]
 
+_STATUS = [
+    "domain: the expressive output side of a face — browser-rendered, reads 3D "
+    "on a flat 2D screen, gaze pointable in any direction",
+    "scaffold: no renderer, no gaze primitive, no render verbs on disk yet",
+    "build brief: https://github.com/agentculture/face-cli/issues/1",
+]
+
 _VERBS = [
     "whoami — identity probe (nick, version, backend, model)",
     "learn — structured self-teaching prompt",
@@ -46,6 +53,7 @@ def agent_sections() -> list[dict[str, object]]:
                 f"model: {ident['model']}",
             ],
         },
+        {"title": "Status", "items": list(_STATUS)},
         {"title": "Verbs", "items": list(_VERBS)},
         {"title": "Sibling-pattern artifacts", "items": list(_ARTIFACTS)},
     ]

{face_cli-0.7.0 → face_cli-0.7.1}/face_cli/cli/_commands/whoami.py

@@ -4,8 +4,8 @@ Reports the agent's identity as declared in ``culture.yaml``: its nick
 (``suffix``), the backend it runs on, and the served model (if any) — plus the
 package version. Read-only; touches nothing but its own ``culture.yaml``.
 
-When you clone this template, rename the package and update ``culture.yaml`` —
-``whoami`` then reflects your new agent's identity with no code change.
+The identity is data, not code: editing ``culture.yaml`` changes what ``whoami``
+reports with no code change.
 """
 
 from __future__ import annotations

{face_cli-0.7.0 → face_cli-0.7.1}/face_cli/explain/catalog.py

@@ -12,11 +12,14 @@ from __future__ import annotations
 _ROOT = """\
 # face-cli
 
-A clonable template for AgentCulture mesh agents. It carries an agent-first CLI
-(cited from the teken `python-cli` reference), a mesh identity (`culture.yaml` +
-`CLAUDE.md`), the canonical guildmaster skill kit under `.claude/skills/`, and a
-buildable/deployable package baseline. Clone it, rename the package, edit
-`culture.yaml`, and you have a new agent.
+The expressive *output* side of a face: a simulated face rendered in a browser
+that appears three-dimensional on a flat 2D screen and can look in any
+direction, drivable by an agent. The sibling `face-recognition-cli` is the
+perceptual *input* side — this tool does no recognition.
+
+**Status: scaffold.** There is no renderer, no gaze primitive, and no render
+verbs on disk yet; what follows is the introspection surface. The build brief
+is <https://github.com/agentculture/face-cli/issues/1>.
 
 ## Verbs
 
@@ -81,7 +84,7 @@ _OVERVIEW = """\
 # face-cli overview
 
 Read-only descriptive snapshot of the agent: identity (from `culture.yaml`), the
-verb surface, and the sibling-pattern artifacts the template carries. Accepts an
+verb surface, and the sibling-pattern artifacts this repo carries. Accepts an
 ignored `target` so a stray path never hard-fails.
 
 ## Usage

{face_cli-0.7.0 → face_cli-0.7.1}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "face-cli"
-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."
+version = "0.7.1"
+description = "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."
 readme = "README.md"
 license = "Apache-2.0"
 requires-python = ">=3.12"

{face_cli-0.7.0 → face_cli-0.7.1}/tests/test_cli.py

@@ -24,6 +24,30 @@ def test_no_args_prints_help(capsys: pytest.CaptureFixture[str]) -> None:
     assert "usage: face-cli" in capsys.readouterr().out
 
 
+def test_root_json_without_verb_emits_command_map(capsys: pytest.CaptureFixture[str]) -> None:
+    """`face --json` (no verb) is the machine-readable analogue of printing help."""
+    rc = main(["--json"])
+    assert rc == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["tool"] == "face-cli"
+    assert payload["commands"]
+
+
+@pytest.mark.parametrize(
+    "argv",
+    [["--json", "whoami"], ["whoami", "--json"]],
+    ids=["flag-before-verb", "flag-after-verb"],
+)
+def test_json_flag_position_does_not_change_meaning(
+    argv: list[str], capsys: pytest.CaptureFixture[str]
+) -> None:
+    """A leading `--json` must survive sub-parsing (each subparser re-defaults it)."""
+    rc = main(argv)
+    assert rc == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["nick"] == "face-cli"
+
+
 def test_unknown_command_errors(capsys: pytest.CaptureFixture[str]) -> None:
     with pytest.raises(SystemExit) as exc:
         main(["bogus"])

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

@@ -165,7 +165,7 @@ wheels = [
 
 [[package]]
 name = "face-cli"
-version = "0.7.0"
+version = "0.7.1"
 source = { editable = "." }
 
 [package.dev-dependencies]