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

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

@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [8.0.0] - 2026-04-22
+
+### Added
+
+- `culture afi`, `culture identity`, and `culture secret` surfaced as (coming soon) namespaces in `culture explain` output. `culture identity` will wrap a future standalone `zehut-cli`; `culture secret` will wrap `shushu-cli`; `culture afi` shares its name with the standalone `afi-cli`.
+
+### Changed
+
+- BREAKING: Renamed `culture agex` to `culture devex` (developer experience) — more familiar terminology and visually distinct from `culture agent`. The upstream `agex-cli` / `agent_experience` library is unchanged; only culture's public command name differs.
+- Positioning docs, README, and site chrome refreshed to reflect the new identity: culture is the framework of agreements that makes agent behavior portable, inspectable, and effective, surfacing explain/overview/learn at every CLI level.
+
 ## [7.4.0] - 2026-04-22
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 7.4.0
+Version: 8.0.0
 Summary: Legacy alias for culture — install culture instead
 Project-URL: Homepage, https://github.com/OriNachum/culture
 Author: Ori Nachum
@@ -25,18 +25,23 @@ Description-Content-Type: text/markdown
 
 # Culture
 
-The complete human-agent collaboration system built around AgentIRC.
+The framework of agreements that makes agent behavior portable, inspectable, and effective.
 
 **AgentIRC** is the IRC-native runtime for persistent AI agents and humans in shared live rooms.
-**Culture** is the full solution — CLI, harnesses, console, workflows, and multi-machine mesh.
+**Culture** is the full solution — CLI with universal introspection verbs (`explain` / `overview` / `learn` at every level), harnesses, console, workflows, and multi-machine mesh. It ships `culture devex` today (powered by the standalone `agex-cli`) and will add `culture afi`, `culture identity`, and `culture secret` next.
 
 ## Start here
 
 - [Quickstart](https://culture.dev/quickstart/) — install and start in 5 minutes
 - [Choose a Harness](https://culture.dev/choose-a-harness/) — Claude Code, Codex, Copilot, ACP
+- [`culture devex` and universal verbs](https://culture.dev/reference/cli/devex/) — the inspectable CLI
 - [AgentIRC Architecture](https://culture.dev/agentirc/architecture-overview/) — the runtime layer
 - [Vision & Patterns](https://culture.dev/vision/) — the broader model
 
+## What's next
+
+`culture afi` (Agent First Interface), `culture identity` (mesh identity / key management, wrapping the standalone `zehut-cli`), and `culture secret` (credential management, wrapping `shushu-cli`) are on the way. Run `culture explain` for the always-current registry of what's ready vs. coming soon.
+
 ## Install
 
 ```bash

agentirc_cli-8.0.0/README.md

@@ -0,0 +1,34 @@
+# Culture
+
+The framework of agreements that makes agent behavior portable, inspectable, and effective.
+
+**AgentIRC** is the IRC-native runtime for persistent AI agents and humans in shared live rooms.
+**Culture** is the full solution — CLI with universal introspection verbs (`explain` / `overview` / `learn` at every level), harnesses, console, workflows, and multi-machine mesh. It ships `culture devex` today (powered by the standalone `agex-cli`) and will add `culture afi`, `culture identity`, and `culture secret` next.
+
+## Start here
+
+- [Quickstart](https://culture.dev/quickstart/) — install and start in 5 minutes
+- [Choose a Harness](https://culture.dev/choose-a-harness/) — Claude Code, Codex, Copilot, ACP
+- [`culture devex` and universal verbs](https://culture.dev/reference/cli/devex/) — the inspectable CLI
+- [AgentIRC Architecture](https://culture.dev/agentirc/architecture-overview/) — the runtime layer
+- [Vision & Patterns](https://culture.dev/vision/) — the broader model
+
+## What's next
+
+`culture afi` (Agent First Interface), `culture identity` (mesh identity / key management, wrapping the standalone `zehut-cli`), and `culture secret` (credential management, wrapping `shushu-cli`) are on the way. Run `culture explain` for the always-current registry of what's ready vs. coming soon.
+
+## Install
+
+```bash
+uv tool install culture
+culture server start
+```
+
+## Documentation
+
+- **[culture.dev](https://culture.dev)** — the full solution: quickstart, harnesses, guides, vision
+- **[culture.dev/agentirc](https://culture.dev/agentirc/)** — the runtime layer: architecture, protocol, federation
+
+## License
+
+[MIT](LICENSE)

{agentirc_cli-7.4.0 → agentirc_cli-8.0.0}/_config.culture.yml

@@ -1,6 +1,6 @@
 title: Culture
 description: >-
-  The professional workspace for agents.
+  The framework of agreements that makes agent behavior portable, inspectable, and effective — a professional workspace for agents with a CLI that explains itself.
 url: "https://culture.dev"
 baseurl: ""
 build_site: culture
@@ -12,7 +12,7 @@ twitter:
 social:
   name: Culture
   links:
-    - https://github.com/OriNachum/culture
+    - https://github.com/agentculture/culture
 
 author:
   name: Ori Nachum
@@ -39,13 +39,15 @@ aux_links:
   "Citation CLI":
     - "/citation-cli/"
   "GitHub":
-    - "https://github.com/OriNachum/culture"
+    - "https://github.com/agentculture/culture"
 
 aux_links_new_tab: false
 
 footer_content: >-
   Culture — human-agent collaboration built around
   <a href="/agentirc/">AgentIRC</a>.
+  Inspectable CLI via <a href="/reference/cli/devex/">culture devex</a>
+  (explain / overview / learn at every level).
   Agent Experience via <a href="https://culture.dev/agex/">agex-cli</a>.
   Code distribution via <a href="/citation-cli/">Citation CLI</a>.
-  Source on <a href="https://github.com/OriNachum/culture">GitHub</a>.
+  Source on <a href="https://github.com/agentculture/culture">GitHub</a>.

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

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

agentirc_cli-8.0.0/culture/cli/devex.py

@@ -0,0 +1,111 @@
+"""`culture devex` — passthrough to the standalone agex CLI.
+
+Also registers universal-verb handlers for the ``devex`` topic so
+``culture explain devex`` / ``culture overview devex`` /
+``culture learn devex`` route through culture's universal-verb path.
+
+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.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import io
+import sys
+
+from culture.cli import introspect
+
+NAME = "devex"
+
+
+def _run_devex(argv: list[str]) -> None:
+    """Invoke the underlying agex typer app in-process.
+
+    Uses standalone_mode=True (the typer default) so typer's own --help,
+    --version, and Exit handling work unchanged. Typer calls ``sys.exit``
+    when done, raising ``SystemExit``; this function lets that propagate
+    so the caller (the ``culture devex`` passthrough) exits with the code
+    the user expects. Callers that need to capture output and translate
+    the exit into a return value should use :func:`_capture_devex` instead.
+    """
+    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)
+
+
+def _capture_devex(argv: list[str]) -> tuple[str, int]:
+    """Run devex with stdout + stderr captured, translating SystemExit.
+
+    The universal-verb handlers need ``(output, exit_code)`` rather than a
+    process-level exit, so we deliberately catch ``SystemExit`` here and
+    translate it into a return value. The :func:`_run_devex` variant is for
+    the passthrough path where the exit must propagate.
+    """
+    buf = io.StringIO()
+    try:
+        with contextlib.redirect_stdout(buf), contextlib.redirect_stderr(buf):
+            _run_devex(argv)
+    except SystemExit as exc:  # NOSONAR S5754 — see docstring
+        # typer calls sys.exit() on completion even for success, so this
+        # is the normal exit path; the trailing `return ... 0` only runs
+        # if _run_devex somehow returns without raising (defensive).
+        code = exc.code
+        if code is None:
+            return buf.getvalue(), 0
+        if isinstance(code, int):
+            return buf.getvalue(), code
+        return buf.getvalue() + str(code), 1
+    return buf.getvalue(), 0
+
+
+# --- universal-verb topic handlers for ``devex`` ---------------------------
+
+
+def _devex_explain(_topic: str | None) -> tuple[str, int]:
+    # The underlying agex library refers to itself as "agex"; that's what
+    # we pass to its own explain verb. The culture-facing name is devex.
+    return _capture_devex(["explain", "agex"])
+
+
+def _devex_overview(_topic: str | None) -> tuple[str, int]:
+    return _capture_devex(["overview", "--agent", "claude-code"])
+
+
+def _devex_learn(_topic: str | None) -> tuple[str, int]:
+    return _capture_devex(["learn", "--agent", "claude-code"])
+
+
+introspect.register_topic(
+    "devex",
+    explain=_devex_explain,
+    overview=_devex_overview,
+    learn=_devex_learn,
+)
+
+
+# --- 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:
+    rest = list(getattr(args, "devex_args", []) or [])
+    _run_devex(rest)

{agentirc_cli-7.4.0 → agentirc_cli-8.0.0}/culture/cli/introspect.py

@@ -68,6 +68,18 @@ def _resolve(verb: str, topic: str | None) -> tuple[str, int]:
     effective = topic if topic is not None else "culture"
     handler = registry.get(effective)
     if handler is None:
+        # Known-but-unregistered namespaces are advertised via _NAMESPACES
+        # in `culture explain` output with "(coming soon)". Surface that
+        # same framing on a direct `culture <verb> <ns>` call instead of
+        # failing as if the topic were unknown. Exit 0 because this is a
+        # known future state, not a user error.
+        if effective in _NAMESPACES:
+            return (
+                f"`culture {effective}` — coming soon. "
+                f"Not yet implemented. Run `culture explain` to see the "
+                f"current registry of namespaces.\n",
+                0,
+            )
         available = sorted(registry.keys())
         msg = (
             f"unknown topic '{effective}' for {verb};"
@@ -89,7 +101,18 @@ def learn(topic: str | None) -> tuple[str, int]:
     return _resolve("learn", topic)
 
 
-_NAMESPACES = ("agex", "server", "agent", "mesh", "bot", "channel", "skills")
+_NAMESPACES = (
+    "agent",
+    "server",
+    "mesh",
+    "channel",
+    "bot",
+    "skills",
+    "devex",
+    "afi",
+    "identity",
+    "secret",
+)
 
 
 def _culture_explain(_topic: str | None) -> tuple[str, int]:

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

@@ -70,6 +70,21 @@ description: Everything in the workspace — grouped by who it's for.
   <a class="feature-group-deep" href="{{ '/agentirc/architecture-overview/' | relative_url }}">Under the hood → AgentIRC</a>
 </div>
 
+<div class="feature-group">
+  <div class="feature-group-head">
+    <span class="feature-group-kicker">05</span>
+    <span class="feature-group-title">Introspection &amp; experience</span>
+  </div>
+  <p class="feature-group-desc">The CLI explains itself. Each namespace owns its own docs.</p>
+  <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 identity / secret (coming soon)</div>
+  </div>
+  <a class="feature-group-deep" href="{{ '/reference/cli/devex/' | relative_url }}">Read the contract →</a>
+</div>
+
 <div class="callout-relationship">
   <p><strong>Want the runtime internals?</strong> AgentIRC is the IRC-native server at the core. <a href="{{ '/agentirc/' | relative_url }}">Explore AgentIRC →</a></p>
 </div>

{agentirc_cli-7.4.0 → agentirc_cli-8.0.0}/docs/culture/index.md

@@ -9,7 +9,7 @@ description: The professional workspace for agents.
 <div class="hero">
   <p class="hero-label">The professional workspace for agents</p>
   <h1 class="hero-headline">Where your agents actually&nbsp;work.</h1>
-  <p class="hero-sub">Persistent rooms. Real colleagues. One CLI. Multi-machine mesh.</p>
+  <p class="hero-sub">Persistent rooms. Real colleagues. A CLI that explains itself. Multi-machine mesh.</p>
   <div>
     <a href="{{ '/quickstart/' | relative_url }}" class="btn-cta btn-cta--primary">Quickstart</a>
     <a href="{{ '/features/' | relative_url }}" class="btn-cta btn-cta--secondary">See the workspace</a>
@@ -28,7 +28,7 @@ description: The professional workspace for agents.
   <div class="stack-row">
     <span class="stack-row-label">You</span>
     <div class="stack-row-content">
-      <strong>Culture CLI</strong> <span class="text-muted">uv tool install culture</span>
+      <strong>Culture CLI</strong> <span class="text-muted">uv tool install culture · explain · overview · learn at every level</span>
     </div>
   </div>
   <div class="stack-row">
@@ -76,6 +76,10 @@ description: The professional workspace for agents.
     <p class="docs-card-title">Join as a Human</p>
     <p class="docs-card-desc">Console or any IRC client</p>
   </a>
+  <a href="{{ '/reference/cli/devex/' | relative_url }}" class="docs-card">
+    <p class="docs-card-title">Inspectable CLI</p>
+    <p class="docs-card-desc">culture explain · overview · learn · devex</p>
+  </a>
 </div>
 
 <div class="callout-relationship">

{agentirc_cli-7.4.0 → agentirc_cli-8.0.0}/docs/culture/mental-model.md

@@ -49,6 +49,21 @@ This is the Reflective Development paradigm: the system is self-improving becaus
 the participants — both human and AI — have access to the same context and the
 same tools.
 
+Reflection is also built into the CLI itself through three **universal verbs**
+available at every level of the command tree:
+
+- `explain X` — deep description of X and everything under X.
+- `overview X` — shallow map of X.
+- `learn X` — agent-facing onboarding prompt for operating X, so an agent
+  doesn't have to re-explore X every time it connects.
+
+Each namespace owns its own handlers — `culture` is pure plumbing. An agent
+can run `culture explain`, `culture explain devex`, `culture overview mesh`,
+or `culture learn agent` and get progressively-scoped self-description
+without leaving the shell. See the
+[`culture devex` reference]({{ '/reference/cli/devex/' | relative_url }})
+for the contract and the current registry of topics.
+
 ## Organization
 
 Multiple Culture instances link together through federation. Each instance is

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

@@ -60,3 +60,26 @@ read and write plain text, which is what language models are built to do.
 The protocol handles presence, channels, messaging, and federation.
 Culture extends it with attention routing, skills, and agent lifecycle
 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`.
+- **`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.
+- **`culture secret`** — Secret management. Wraps a standalone
+  `shushu-cli`. Handles credentials and sensitive config for agents and
+  harnesses.
+
+Culture uses English for its first-class nouns; the standalone CLIs keep
+their brand names. You don't have to remember which is which —
+`culture explain` is the always-current source of truth and lists each
+namespace's current state (registered vs. coming soon) at runtime.

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

@@ -3,7 +3,7 @@ title: "What is Culture?"
 parent: "Vision & Patterns"
 nav_order: 1
 sites: [culture]
-description: Culture is a professional workspace for specialized agents. Here's what that means.
+description: Culture is the framework that makes agent behavior portable, inspectable, and effective — a professional workspace for specialized agents.
 permalink: /what-is-culture/
 redirect_from:
   - /why-culture/
@@ -11,12 +11,14 @@ redirect_from:
 
 # What is Culture?
 
-Culture is a professional workspace for specialized agents. Through AgentIRC,
-it provides the shared environment — rooms, presence, roles, coordination,
-and history that persists across sessions — where agents and humans work
-together. Harnesses are optional connectors: they let an agent stay present
-in the culture without being pushed to read every message, so participating
-in the workspace doesn't mean drowning in it.
+Culture is the framework of agreements that makes agent behavior portable,
+inspectable, and effective. Concretely, it provides two things: a shared
+professional workspace for specialized agents (rooms, presence, roles,
+coordination, and history via AgentIRC), and a CLI whose every level
+explains itself so agents can operate the system without re-discovering it
+each session. Harnesses are optional connectors: they let an agent stay
+present in the culture without being pushed to read every message, so
+participating in the workspace doesn't mean drowning in it.
 
 ## A professional workspace for specialized agents
 
@@ -47,6 +49,24 @@ Teachability is real and important — but it is not what sets Culture apart.
 What sets Culture apart is the shared professional workspace of specialized
 agents.
 
+## Inspectable from any level
+
+Culture ships three **universal verbs** — `explain`, `overview`, and
+`learn` — available at every level of the CLI command tree, each scoped
+to that node and its descendants:
+
+- `culture explain [topic]` — full description (deep).
+- `culture overview [topic]` — shallow map.
+- `culture learn [topic]` — agent-facing onboarding prompt so an agent
+  can operate the topic without re-exploring it each session.
+
+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.
+
 ## Reference points
 
 Systems like OpenClaw are useful reference points because they focus on the
@@ -69,3 +89,4 @@ not a replacement for what they already carry.
 - For the broader model and where this is going → [Vision]({{ '/vision/' | relative_url }}).
 - For the conceptual model (spaces, membership, reflection) → [Mental model]({{ '/mental-model/' | relative_url }}).
 - For the capability list → [Features]({{ '/features/' | relative_url }}).
+- For the CLI's self-explaining surface → [`culture devex` and universal verbs]({{ '/reference/cli/devex/' | relative_url }}).

agentirc_cli-8.0.0/docs/reference/cli/devex.md

@@ -0,0 +1,130 @@
+---
+title: "culture devex"
+parent: "CLI"
+grand_parent: "Reference"
+nav_order: 10
+sites: [agentirc, culture]
+description: "Developer-experience passthrough and universal introspection verbs."
+permalink: /reference/cli/devex/
+redirect_from:
+  - /reference/cli/agex/
+---
+
+# `culture devex` and universal verbs
+
+Culture ships a developer-experience namespace as a first-class citizen.
+`culture devex` is powered by the standalone
+[`agex-cli`]({{ site.data.sites.agex }}) library (`agent_experience`
+Python package). The command name differs for familiarity with the
+developer-experience vocabulary; the underlying tool is the same. Two
+affordances:
+
+## `culture devex <anything>`
+
+A full passthrough to the standalone `agex` CLI. Everything after
+`culture devex` is forwarded verbatim to the typer app. Exit codes
+propagate.
+
+```bash
+culture devex --version
+culture devex explain agex
+culture devex overview --agent claude-code
+culture devex learn --agent claude-code
+```
+
+`culture devex --help` shows the underlying CLI's help, not culture's.
+
+The passthrough forwards the argument vector verbatim, so the library's
+own topic names (for example `agex` as an explain topic) are what you
+pass on the devex subcommand. When you reach for culture's universal
+verbs, use the culture-facing names (`devex`, not `agex`).
+
+## 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 X` | Full description of X and everything under X (deep) |
+| `overview X` | Summary of X (shallow map view) |
+| `learn X` | Agent-facing onboarding prompt for operating X |
+
+```bash
+culture explain           # describes culture + its namespaces
+culture explain devex     # routes to devex's explain handler
+culture overview          # culture map
+culture learn             # agent onboarding prompt for culture
+culture learn devex       # agent onboarding for devex
+```
+
+`learn` produces an agent-facing self-teaching prompt so an agent doesn't
+have to re-explore a tool every time. This matches the underlying
+`agex learn` verb semantically.
+
+## Each namespace owns its own
+
+Culture is pure plumbing: a tiny internal dispatcher
+(`culture/cli/introspect.py`) maps topics to handlers. Each namespace
+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
+
+Three more namespaces are registered 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
+  `shushu-cli`.
+
+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.
+
+## For namespace authors
+
+A new namespace plugs into the universal verbs by calling
+`introspect.register_topic(...)` at module import time:
+
+```python
+# culture/cli/mycmd.py
+from culture.cli import introspect
+
+
+def _explain(_topic):
+    return "markdown describing mycmd ...\n", 0
+
+
+def _overview(_topic):
+    return "one-line summary of mycmd\n", 0
+
+
+def _learn(_topic):
+    return "agent onboarding prompt for mycmd\n", 0
+
+
+introspect.register_topic(
+    "mycmd",
+    explain=_explain,
+    overview=_overview,
+    learn=_learn,
+)
+```
+
+Each handler has signature `Handler = Callable[[str | None], tuple[str, int]]` —
+it receives the topic (may be `None`) and returns `(stdout, exit_code)`.
+
+### CLI group protocol: `NAME` vs `NAMES`
+
+A normal group module (e.g. `server`, `agent`) exports a singular
+`NAME: str` — the subcommand noun. A group that owns multiple top-level
+verbs (e.g. `introspect`, which owns all three of `explain`/`overview`/
+`learn`) exports a plural `NAMES: frozenset[str]` instead. The dispatch
+loop in `culture/cli/__init__.py` honors both — `NAMES` takes priority
+with `{NAME}` as the fallback — so most groups only need `NAME`.

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

@@ -10,7 +10,11 @@ permalink: /reference/cli/
 
 # CLI Reference
 
-The `culture` command manages servers, agents, and network observation.
+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.
 
 Install: `uv tool install culture` or `pip install culture`
 
@@ -395,9 +399,14 @@ The legacy `~/.culture/agents.yaml` format is still supported; use `culture agen
 ## Universal verbs
 
 Available at the root of the command tree. See
-[`culture agex`](./agex/) for detail.
+[`culture devex` and universal verbs](./devex/) for the contract and the
+registry of participating namespaces.
 
 - `culture explain [topic]` — deep description
 - `culture overview [topic]` — shallow summary
 - `culture learn [topic]` — agent onboarding prompt
-- `culture agex <anything>` — passthrough to the agex CLI
+- `culture devex <anything>` — developer-experience passthrough
+  (powered by `agex-cli`)
+
+`culture afi`, `culture identity`, and `culture secret` are upcoming
+and appear as `(coming soon)` in `culture explain` output.

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

@@ -1,6 +1,6 @@
 [project]
 name = "agentirc-cli"
-version = "7.4.0"
+version = "8.0.0"
 description = "Legacy alias for culture — install culture instead"
 readme = "README.md"
 license = "MIT"