agentirc-cli 8.0.0__tar.gz → 8.1.0__tar.gz

{agentirc_cli-8.0.0 → agentirc_cli-8.1.0}/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [8.1.0] - 2026-04-23
+
+### Added
+
+- `culture afi` namespace — passthrough to the standalone `afi-cli` (Agent First Interface scaffolder) with argparse-REMAINDER argument forwarding, parallel to `culture devex`.
+- Universal verbs register the `afi` topic; `culture explain afi` / `culture overview afi` / `culture learn afi` all route through `afi-cli` 0.3+ and `culture explain` no longer marks `culture afi` as coming-soon.
+- `afi-cli>=0.3,<1.0` as a library dependency (0.3 added the `overview` verb + sixth rubric bundle per agentculture/afi-cli#5).
+- `culture/cli/_passthrough.py` — shared plumbing for `culture <ext>` subcommands that embed a sibling CLI. Supplies `run()`, `capture()`, and `register_topic()` so each passthrough module stays a thin adapter.
+
+### Changed
+
+- `culture/cli/devex.py` refactored onto the new shared passthrough helper. Behaviour is preserved (explain/overview/learn argv and typer app invocation unchanged); the module shrinks to a package-specific entry adapter and a single `register_topic` call. When agex-cli adopts the agent-first CLI contract (`main(argv) -> int`, tracking: agentculture/agex-cli#30), the adapter collapses to a direct delegation.
+
 ## [8.0.0] - 2026-04-22
 
 ### Added

{agentirc_cli-8.0.0 → agentirc_cli-8.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 8.0.0
+Version: 8.1.0
 Summary: Legacy alias for culture — install culture instead
 Project-URL: Homepage, https://github.com/OriNachum/culture
 Author: Ori Nachum
@@ -12,6 +12,7 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Communications :: Chat :: Internet Relay Chat
 Requires-Python: >=3.12
+Requires-Dist: afi-cli<1.0,>=0.3
 Requires-Dist: agex-cli<1.0,>=0.13
 Requires-Dist: aiohttp>=3.9
 Requires-Dist: anthropic>=0.40

{agentirc_cli-8.0.0 → agentirc_cli-8.1.0}/culture/cli/__init__.py

@@ -8,6 +8,7 @@ Commands are organized into noun-based groups:
     culture bot      {create,start,stop,list,inspect,archive,unarchive}
     culture skills   {install}
     culture devex    {...developer-experience passthrough (powered by agex-cli)...}
+    culture afi      {...agent-first interface passthrough (powered by afi-cli)...}
 
 Universal verbs (available at the root):
     culture explain [topic]    full description of topic (default: culture)
@@ -22,9 +23,9 @@ import logging
 import sys
 
 from culture import __version__
-from culture.cli import agent, bot, channel, devex, introspect, mesh, server, skills
+from culture.cli import afi, agent, bot, channel, devex, introspect, mesh, server, skills
 
-GROUPS = [agent, server, mesh, channel, bot, skills, devex, introspect]
+GROUPS = [agent, server, mesh, channel, bot, skills, devex, afi, introspect]
 
 
 def _names_of(group) -> set[str]:

agentirc_cli-8.1.0/culture/cli/_passthrough.py

@@ -0,0 +1,116 @@
+"""Shared plumbing for `culture <ext>` passthrough subcommands.
+
+A passthrough module (e.g. ``culture devex``, ``culture afi``) embeds a
+sibling CLI in-process: arguments after the namespace token are forwarded
+verbatim to the external CLI's entry callable, and the three universal
+verbs (``explain`` / ``overview`` / ``learn``) capture the external CLI's
+output and route it through :mod:`culture.cli.introspect`.
+
+Each passthrough module supplies a package-specific ``Entry`` callable
+with signature ``(argv: list[str]) -> int | None``. The callable may:
+
+* return ``None`` or ``0`` for success,
+* return a non-zero ``int`` for a handled error,
+* raise ``SystemExit`` for argparse ``--help`` / ``--version`` / errors
+  or typer's standalone-mode hard-exit on completion.
+
+:func:`run` propagates via ``sys.exit`` (for the ``dispatch()`` path).
+:func:`capture` collects stdout+stderr and translates ``SystemExit`` into
+an ``int`` return code (for the universal-verb handlers, which must
+return ``(stdout, rc)``).
+
+The long-term target is every embedded CLI exposing a clean
+``main(argv) -> int`` (agent-first CLI contract owned by afi-cli). Until
+then, typer-backed CLIs like agex-cli can be wrapped in a small entry
+adapter that calls the typer ``app`` — the plumbing here stays unchanged.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import sys
+from typing import Callable
+
+from culture.cli import introspect
+
+Entry = Callable[[list[str]], "int | None"]
+
+
+def _translate_exit(code: "int | str | None") -> "tuple[int, str | None]":
+    """Map a ``SystemExit.code`` to ``(rc, message)``.
+
+    Python's ``sys.exit`` accepts ``None`` (rc 0), an ``int`` (rc = int), or
+    anything else (rc 1 with the stringified value printed to stderr). We
+    mirror all three so an embedded CLI using any ``sys.exit`` form is
+    surfaced to culture's caller the way a bare invocation would be.
+    """
+    if code is None:
+        return 0, None
+    if isinstance(code, int):
+        return code, None
+    return 1, str(code)
+
+
+def run(entry: Entry, argv: list[str]) -> None:
+    """Invoke ``entry(argv)`` and ``sys.exit`` with its return code.
+
+    Used by a group module's ``dispatch()`` to forward arguments verbatim to
+    the embedded CLI. ``SystemExit`` raised inside the entry (typer's
+    hard-exit, argparse's ``--help`` / ``--version`` / error path, or
+    ``sys.exit("msg")``) is caught, its message (if any) forwarded to
+    stderr, and its code re-emitted via ``sys.exit`` so the behaviour
+    matches a bare invocation of the embedded CLI.
+    """
+    try:
+        rc = entry(argv) or 0
+    except SystemExit as exc:  # NOSONAR S5754 — SystemExit is re-emitted via sys.exit below
+        rc, message = _translate_exit(exc.code)
+        if message is not None:
+            print(message, file=sys.stderr)
+    sys.exit(rc)
+
+
+def capture(entry: Entry, argv: list[str]) -> tuple[str, int]:
+    """Invoke ``entry(argv)`` with stdout+stderr captured; return ``(out, rc)``.
+
+    Used by universal-verb handlers (``explain`` / ``overview`` / ``learn``),
+    which must return a value rather than exit. ``SystemExit`` raised inside
+    the entry is translated into the ``rc`` half of the return tuple; any
+    string-valued ``exc.code`` is appended to the captured buffer so the
+    embedded CLI's error text reaches the caller the way a bare invocation
+    would emit it on stderr.
+    """
+    buf = io.StringIO()
+    rc = 0
+    try:
+        with contextlib.redirect_stdout(buf), contextlib.redirect_stderr(buf):
+            rc = entry(argv) or 0
+    except SystemExit as exc:  # NOSONAR S5754 — code is surfaced as rc; behaviour documented above
+        rc, message = _translate_exit(exc.code)
+        if message is not None:
+            buf.write(message)
+            if not message.endswith("\n"):
+                buf.write("\n")
+    return buf.getvalue(), rc
+
+
+def register_topic(
+    topic: str,
+    entry: Entry,
+    *,
+    explain_argv: list[str],
+    overview_argv: list[str],
+    learn_argv: list[str],
+) -> None:
+    """Register ``explain`` / ``overview`` / ``learn`` handlers for ``topic``.
+
+    Each handler captures the output of ``entry(<verb_argv>)`` and returns
+    ``(stdout, rc)`` per the :mod:`culture.cli.introspect` handler protocol.
+    """
+    introspect.register_topic(
+        topic,
+        explain=lambda _t: capture(entry, explain_argv),
+        overview=lambda _t: capture(entry, overview_argv),
+        learn=lambda _t: capture(entry, learn_argv),
+    )

agentirc_cli-8.1.0/culture/cli/afi.py

@@ -0,0 +1,71 @@
+"""`culture afi` — passthrough to the standalone afi CLI.
+
+afi (Agent First Interface) scaffolds and audits agent-first CLIs, MCP
+servers, and HTTP sites. Culture embeds it as a first-class namespace so
+the culture CLI exposes the same agent-first affordances afi enforces.
+
+This module is a thin adapter: it supplies a package-specific ``Entry``
+callable and wires the three universal verbs
+(``explain`` / ``overview`` / ``learn``) through
+:mod:`culture.cli._passthrough`. afi already implements the agent-first
+CLI contract (``main(argv) -> int``), so the entry is a direct
+delegation — no typer adapter needed.
+
+``afi-cli`` owns the rubric the contract is measured against. See
+`agentculture/afi-cli#5 <https://github.com/agentculture/afi-cli/issues/5>`_
+for the tracking issue that adds an ``overview`` verb + rubric bundle so
+afi models every check it enforces.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from culture.cli import _passthrough
+
+NAME = "afi"
+
+
+def _entry(argv: list[str]) -> "int | None":
+    """In-process call into ``afi.cli.main(argv)``.
+
+    afi's ``main`` returns an ``int`` on normal completion and raises
+    ``SystemExit`` only for argparse-level exits (``--help``, ``--version``,
+    unknown flag). Both paths are handled by :mod:`culture.cli._passthrough`.
+    """
+    try:
+        from afi.cli import main
+    except ImportError as exc:  # pragma: no cover — declared dep
+        print(f"afi-cli is not installed: {exc}", file=sys.stderr)
+        sys.exit(2)
+    return main(argv)
+
+
+_passthrough.register_topic(
+    "afi",
+    _entry,
+    explain_argv=["explain"],
+    overview_argv=["overview"],
+    learn_argv=["learn"],
+)
+
+
+# --- CLI group protocol ---------------------------------------------------
+
+
+def register(subparsers: "argparse._SubParsersAction") -> None:
+    # prefix_chars=chr(0): every token (including --help, --version) is
+    # treated as positional and captured in afi_args for the underlying
+    # afi argparse parser to handle.
+    p = subparsers.add_parser(
+        NAME,
+        help="Run the afi agent-first CLI via passthrough",
+        add_help=False,
+        prefix_chars=chr(0),
+    )
+    p.add_argument("afi_args", nargs=argparse.REMAINDER, help="Arguments passed to afi")
+
+
+def dispatch(args: argparse.Namespace) -> None:
+    _passthrough.run(_entry, list(getattr(args, "afi_args", []) or []))

agentirc_cli-8.1.0/culture/cli/devex.py

@@ -0,0 +1,71 @@
+"""`culture devex` — passthrough to the standalone agex CLI.
+
+Under the hood, ``devex`` is powered by the standalone ``agex-cli``
+(``agent_experience`` package). The command name differs for familiarity
+with the developer-experience vocabulary; the underlying tool is the
+same.
+
+This module is a thin adapter: it supplies a package-specific ``Entry``
+callable and wires the three universal verbs
+(``explain`` / ``overview`` / ``learn``) through
+:mod:`culture.cli._passthrough`. When agex-cli migrates to the
+agent-first CLI contract (``main(argv) -> int``), the adapter becomes a
+one-line ``return main(argv)`` without touching the shared plumbing.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from culture.cli import _passthrough
+
+NAME = "devex"
+
+
+def _entry(argv: list[str]) -> None:
+    """In-process call into the agex typer ``app``.
+
+    Typer's default ``standalone_mode=True`` makes ``app`` call ``sys.exit``
+    when it finishes — so this function naturally raises ``SystemExit``,
+    which :mod:`culture.cli._passthrough` translates into an ``int`` for the
+    universal-verb handlers and re-emits via ``sys.exit`` for the direct
+    passthrough path.
+    """
+    try:
+        from agent_experience.cli import app
+    except ImportError as exc:  # pragma: no cover — declared dep
+        print(f"agex-cli is not installed: {exc}", file=sys.stderr)
+        sys.exit(2)
+    app(args=argv)
+
+
+# The underlying agex library refers to itself as "agex"; we pass that to
+# its own explain verb. The culture-facing name is devex.
+_passthrough.register_topic(
+    "devex",
+    _entry,
+    explain_argv=["explain", "agex"],
+    overview_argv=["overview", "--agent", "claude-code"],
+    learn_argv=["learn", "--agent", "claude-code"],
+)
+
+
+# --- CLI group protocol ---------------------------------------------------
+
+
+def register(subparsers: "argparse._SubParsersAction") -> None:
+    # prefix_chars=chr(0) means the devex subparser has no recognized flag
+    # prefix character, so every token (including --help, --version) is
+    # treated as positional and captured in devex_args for typer to handle.
+    p = subparsers.add_parser(
+        NAME,
+        help="Run the agex developer-experience CLI via passthrough",
+        add_help=False,
+        prefix_chars=chr(0),
+    )
+    p.add_argument("devex_args", nargs=argparse.REMAINDER, help="Arguments passed to agex")
+
+
+def dispatch(args: argparse.Namespace) -> None:
+    _passthrough.run(_entry, list(getattr(args, "devex_args", []) or []))

{agentirc_cli-8.0.0 → agentirc_cli-8.1.0}/docs/culture/features.md

@@ -79,7 +79,7 @@ description: Everything in the workspace — grouped by who it's for.
   <div class="feature-group-items">
     <div>culture explain / overview / learn</div>
     <div>culture devex (powered by agex-cli)</div>
-    <div>culture afi (coming soon)</div>
+    <div>culture afi (powered by afi-cli)</div>
     <div>culture identity / secret (coming soon)</div>
   </div>
   <a class="feature-group-deep" href="{{ '/reference/cli/devex/' | relative_url }}">Read the contract →</a>

{agentirc_cli-8.0.0 → agentirc_cli-8.1.0}/docs/culture/vision.md

@@ -64,14 +64,14 @@ management — but the foundation is standard IRC.
 ## Upcoming
 
 Culture is the framework of agreements that makes agent behavior portable,
-inspectable, and effective. Beyond the workspace runtime and the
-[`culture devex`]({{ '/reference/cli/devex/' | relative_url }}) namespace
-(powered by the standalone `agex-cli`) that already ship, three more
-first-class namespaces are next:
-
-- **`culture afi`** — Agent First Interface. Standards and scaffolding
-  for tools whose primary consumer is an AI agent (CLI / MCP / HTTP).
-  Wraps the standalone `afi-cli`.
+inspectable, and effective. Beyond the workspace runtime and the two
+first-class passthrough namespaces that already ship —
+[`culture devex`]({{ '/reference/cli/devex/' | relative_url }}) (powered
+by `agex-cli`) and
+[`culture afi`]({{ '/reference/cli/afi/' | relative_url }}) (powered by
+the standalone `afi-cli`, the Agent First Interface scaffolder) — two
+more first-class namespaces are next:
+
 - **`culture identity`** — Identity management across the mesh. Wraps a
   standalone `zehut-cli` (Hebrew: "identity"). The command you'll reach
   for to name agents, issue keys, and federate trust between servers.

{agentirc_cli-8.0.0 → agentirc_cli-8.1.0}/docs/culture/what-is-culture.md

@@ -62,10 +62,11 @@ to that node and its descendants:
 
 Each namespace owns its own handlers — culture is pure plumbing. Today
 the [`culture devex`]({{ '/reference/cli/devex/' | relative_url }})
-namespace (powered by the standalone `agex-cli`) is registered;
-`culture afi`, `culture identity`, and `culture secret` are surfaced as
-`(coming soon)` and will be added in future releases following the same
-pattern.
+namespace (powered by `agex-cli`) and the
+[`culture afi`]({{ '/reference/cli/afi/' | relative_url }}) namespace
+(powered by `afi-cli`) are registered; `culture identity` and
+`culture secret` remain `(coming soon)` and will be added in future
+releases following the same pattern.
 
 ## Reference points
 

agentirc_cli-8.1.0/docs/reference/cli/afi.md

@@ -0,0 +1,95 @@
+---
+title: "culture afi"
+parent: "CLI"
+grand_parent: "Reference"
+nav_order: 11
+sites: [agentirc, culture]
+description: "Agent First Interface passthrough and universal introspection verbs."
+permalink: /reference/cli/afi/
+---
+
+# `culture afi` and universal verbs
+
+Culture ships the **Agent First Interface** (afi) as a first-class
+namespace. `culture afi` is powered by the standalone
+[`afi-cli`](https://github.com/agentculture/afi-cli) (Python package
+`afi`). afi generates and audits agent-first CLIs, MCP servers, and
+HTTP sites — and models, on itself, every pattern it enforces on
+others.
+
+Two affordances:
+
+## `culture afi <anything>`
+
+A full passthrough to the standalone `afi` CLI. Everything after
+`culture afi` is forwarded verbatim to the argparse app. Exit codes
+propagate.
+
+```bash
+culture afi --version
+culture afi explain
+culture afi learn
+culture afi cli verify .
+```
+
+`culture afi --help` shows the underlying afi argparse help, not
+culture's.
+
+afi itself is argparse-based and exposes a library-grade
+`afi.cli.main(argv) -> int` entry point. Culture embeds it in-process
+via the shared passthrough helper at `culture/cli/_passthrough.py`;
+stdout and stderr from afi are captured cleanly and exit codes are
+preserved.
+
+## Universal verbs: `explain` / `overview` / `learn`
+
+Three verbs live at the root of the culture command tree. Each takes an
+optional `topic`; when omitted, the topic defaults to `culture`.
+
+| Verb | Meaning |
+|------|---------|
+| `explain afi` | Full markdown description of afi (routes to `afi explain`) |
+| `overview afi` | Shallow map of afi (routes to `afi overview`) |
+| `learn afi` | Agent-facing onboarding prompt for operating afi |
+
+```bash
+culture explain afi    # markdown docs for afi root
+culture overview afi   # shallow map
+culture learn afi      # agent onboarding prompt for afi
+```
+
+All three verbs are live from culture 8.1.0 + `afi-cli` 0.3.0 onward;
+the `overview` verb and its rubric bundle were added in
+[agentculture/afi-cli#5](https://github.com/agentculture/afi-cli/issues/5).
+
+## Each namespace owns its own
+
+Culture is pure plumbing — the dispatcher at
+`culture/cli/introspect.py` maps topics to handlers, and the shared
+embedder at `culture/cli/_passthrough.py` provides the in-process
+call, output capture, and `SystemExit` translation. `afi.py` is a thin
+adapter: it supplies the package-specific entry callable and one call
+to `_passthrough.register_topic`. Adding another namespace that wraps
+a sibling CLI follows the same recipe.
+
+### Sibling namespaces
+
+| Namespace | Backing CLI | State |
+|-----------|-------------|-------|
+| `culture devex` | `agex-cli` (`agent_experience`) | Registered |
+| `culture afi` | `afi-cli` (`afi`) | Registered |
+| `culture identity` | future `zehut-cli` | Coming soon |
+| `culture secret` | future `shushu-cli` | Coming soon |
+
+Culture uses English for its first-class nouns; the underlying CLIs
+keep their brand names. `culture explain` is the always-current source
+of truth for which namespaces are ready vs. coming soon.
+
+## See also
+
+- [`culture devex` and universal verbs](./devex/) — the parallel
+  passthrough for the developer-experience CLI, and the full handler
+  protocol for namespace authors.
+- [afi-cli on GitHub](https://github.com/agentculture/afi-cli) — the
+  standalone tool, its rubric, and the spec for what makes a CLI
+  agent-first.

{agentirc_cli-8.0.0 → agentirc_cli-8.1.0}/docs/reference/cli/devex.md

@@ -70,14 +70,13 @@ that wants to participate registers its own handlers on import. For
 `devex`, the `agex-cli` library already implements the three verbs —
 culture just routes.
 
-### Upcoming namespaces
+### Sibling and upcoming namespaces
 
-Three more namespaces are registered as `(coming soon)` in
-`culture explain` output and will gain full handlers in future releases:
+[`culture afi`](./afi/) is registered as of culture 8.1, riding the
+same passthrough plumbing as devex. Two more namespaces are listed as
+`(coming soon)` in `culture explain` output and will gain full
+handlers in future releases:
 
-- **`culture afi`** — Agent First Interface. Scaffolding standards for
-  tools whose primary consumer is an AI agent. Wraps the standalone
-  [`afi-cli`](https://github.com/agentculture/afi-cli).
 - **`culture identity`** — Identity management across the mesh. Will
   wrap a standalone `zehut-cli` (Hebrew: "identity").
 - **`culture secret`** — Secret management. Will wrap a standalone

{agentirc_cli-8.0.0 → agentirc_cli-8.1.0}/docs/reference/cli/index.md

@@ -11,10 +11,12 @@ permalink: /reference/cli/
 # CLI Reference
 
 The `culture` command manages servers, agents, bots, channels, and the
-mesh, plus embeds the agex developer-experience CLI as `culture devex`.
-Every level of the command tree is inspectable via three universal
-verbs — `explain`, `overview`, `learn`. See
-[`culture devex` and universal verbs](./devex/) for the full contract.
+mesh, and embeds two sibling CLIs: the agex developer-experience CLI
+as [`culture devex`](./devex/) and the afi Agent-First-Interface CLI
+as [`culture afi`](./afi/). Every level of the command tree is
+inspectable via three universal verbs — `explain`, `overview`,
+`learn`. See [`culture devex` and universal verbs](./devex/) for the
+full contract.
 
 Install: `uv tool install culture` or `pip install culture`
 
@@ -407,6 +409,8 @@ registry of participating namespaces.
 - `culture learn [topic]` — agent onboarding prompt
 - `culture devex <anything>` — developer-experience passthrough
   (powered by `agex-cli`)
+- `culture afi <anything>` — Agent First Interface passthrough
+  (powered by `afi-cli`)
 
-`culture afi`, `culture identity`, and `culture secret` are upcoming
-and appear as `(coming soon)` in `culture explain` output.
+`culture identity` and `culture secret` are upcoming and appear as
+`(coming soon)` in `culture explain` output.

{agentirc_cli-8.0.0 → agentirc_cli-8.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentirc-cli"
-version = "8.0.0"
+version = "8.1.0"
 description = "Legacy alias for culture — install culture instead"
 readme = "README.md"
 license = "MIT"
@@ -21,6 +21,7 @@ dependencies = [
     "aiohttp>=3.9",
     "textual>=1.0",
     "agex-cli>=0.13,<1.0",
+    "afi-cli>=0.3,<1.0",
 ]
 
 [project.urls]

agentirc_cli-8.1.0/tests/test_cli_afi.py

@@ -0,0 +1,111 @@
+"""Tests for `culture afi` passthrough and `afi` universal topic."""
+
+import subprocess
+import sys
+
+
+def test_culture_afi_version_runs():
+    result = subprocess.run(
+        [sys.executable, "-m", "culture", "afi", "--version"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert result.returncode == 0, result.stderr
+    # afi --version prints "afi X.Y.Z"
+    assert result.stdout.strip().startswith("afi ")
+
+
+def test_culture_afi_explain_runs():
+    result = subprocess.run(
+        [sys.executable, "-m", "culture", "afi", "explain"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip()
+
+
+def test_culture_afi_learn_runs():
+    result = subprocess.run(
+        [sys.executable, "-m", "culture", "afi", "learn"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip()
+
+
+def test_culture_afi_overview_runs():
+    # afi-cli 0.3+ exposes `overview`; our pin guarantees it.
+    result = subprocess.run(
+        [sys.executable, "-m", "culture", "afi", "overview"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip()
+
+
+def test_culture_afi_help_shows_argparse_help():
+    result = subprocess.run(
+        [sys.executable, "-m", "culture", "afi", "--help"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert result.returncode == 0
+    # afi uses argparse; help text contains the usage banner
+    assert "usage:" in result.stdout.lower()
+
+
+def test_culture_explain_afi_via_universal_verb():
+    result = subprocess.run(
+        [sys.executable, "-m", "culture", "explain", "afi"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip()
+
+
+def test_culture_learn_afi_via_universal_verb():
+    result = subprocess.run(
+        [sys.executable, "-m", "culture", "learn", "afi"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip()
+
+
+def test_culture_overview_afi_via_universal_verb():
+    result = subprocess.run(
+        [sys.executable, "-m", "culture", "overview", "afi"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip()
+
+
+def test_culture_explain_lists_afi_as_registered():
+    # When afi registers handlers, `culture explain` should no longer show it
+    # as "(coming soon)".
+    result = subprocess.run(
+        [sys.executable, "-m", "culture", "explain"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert result.returncode == 0, result.stderr
+    lines = [ln for ln in result.stdout.splitlines() if "`culture afi`" in ln]
+    assert lines, "afi line missing from `culture explain` namespaces list"
+    # The line must not carry the "(coming soon)" marker
+    assert "coming soon" not in lines[0], lines[0]