hyperspell-brain 0.4.0__tar.gz

hyperspell_brain-0.4.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc

hyperspell_brain-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hyperspell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hyperspell_brain-0.4.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: hyperspell-brain
+Version: 0.4.0
+Summary: hyperbrain — an agent-first CLI for the Hyperspell company brain
+Author-email: Hyperspell <hello@hyperspell.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: hyperspell<1,>=0.36
+Requires-Dist: typer<1,>=0.12
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.28; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# hyperbrain — agent-first CLI for the Hyperspell company brain
+
+Hyperspell is the brain for your business — the memory layer that unifies
+everything your company knows. `hyperbrain` is the command line into it: one verb
+that humans *and* agents use to query, write, and synthesize that memory.
+Structured JSON by default, pipe-friendly, no interactive prompts required.
+
+```bash
+hyperbrain ask "what's our deployment strategy?"      # synthesized answer + sources
+hyperbrain search "rds proxy" --source slack -n 5     # ranked documents, no synthesis
+echo "remember this" | hyperbrain remember            # write knowledge in
+hyperbrain brain generate                             # (re)build the company-brain tree
+hyperbrain memories status                            # indexing progress per source
+hyperbrain schema                                     # dump the command tree as JSON
+```
+
+## Why this exists
+
+If agents are the primary consumer, why a CLI and not just the API? Because the
+CLI is the **universal adapter**. Any agent that can spawn a shell — Claude Code,
+Cursor, a cron job, an autonomous worker you haven't built yet — can use `hyperbrain`
+with zero bespoke integration. No protocol to implement, no server to run, no SDK
+to vendor. Where MCP says "speak this protocol," `hyperbrain` says "here's a verb."
+
+It's best understood as one half of a pair:
+
+- **Passive context** — the sync daemon writes the synthesized company brain into
+  `~/.hyperspell/` and injects it into every agent's `CLAUDE.md` / `AGENTS.md` /
+  `.cursorrules`. Agents *start* with company context without asking.
+- **Active query** — when the synced summary isn't enough, the agent calls `hyperbrain`
+  to go deeper on demand.
+
+Neither alone is the point: the summary is cheap but shallow, `hyperbrain ask` is deep
+but costs a round-trip. Together, an agent has a free baseline and an escape hatch.
+
+And note the framing: this is a **brain / memory layer**, not retrieval-as-a-service.
+Anyone can do vector search. The value — and the hard part — is keeping a *living,
+curated, coherent* company memory that's current. `hyperbrain brain generate` (synthesis) and
+`hyperbrain remember` (write-back) point at that; raw `search` is just the primitive
+underneath.
+
+## How it's used best
+
+**The highest-leverage move is to register `hyperbrain` as a tool your agents can call**,
+and let them decide when to consult company memory. `hyperbrain schema` exists precisely
+so an agent can introspect every capability as JSON.
+
+Pick the right verb and effort for the job:
+
+| Want | Command | Why |
+|---|---|---|
+| A grounded answer | `hyperbrain ask "…"` | synthesizes + cites; defaults to **all connected sources** |
+| Raw material for another tool | `hyperbrain search "…"` | ranked docs, no LLM — the composable primitive |
+| Speed | `-e minimal` / `low` | verbatim retrieval, or a single LLM query-rewrite |
+| Genuinely multi-hop questions | `-e medium` / `high` | agentic refinement loop (up to 3 / 6 rounds) |
+
+Lean into composability — this is where it beats a UI:
+
+```bash
+hyperbrain ask "what's our deploy process?" -o json | jq -r .answer   # clean text for a prompt
+hyperbrain search "rds proxy" --source slack -n 20 | jq '.documents[].title'
+hyperbrain schema | jq                                                # discover every capability
+```
+
+**Close the loop.** A brain only gets smarter if knowledge flows back in. Treat
+`remember` as a habit — decisions, postmortems, the "why" behind a choice — so future
+queries (by humans *or* agents) surface it:
+
+```bash
+echo "Decision: standardizing on X because Y" | hyperbrain remember --title "arch decision"
+```
+
+Rule of thumb: scope tight (`--source`, low effort) for speed and precision; go broad
+and high-effort only for hard, cross-source questions. The UI *shows* you the brain —
+the CLI lets your agents **think with it**.
+
+## Auth
+
+Reuses the sync daemon's `~/.hyperspell/config.toml` — if you've run
+`hyperspell login` or `hyperspell install`, `hyperbrain` just works. Otherwise pass
+`--api-key` or set `HYPERSPELL_API_KEY` (a long-lived API key or a device JWT).
+
+Precedence: flags > environment > `~/.hyperspell/config.toml` > defaults.
+
+## Agent-first contract
+
+- **JSON by default** to stdout when not a TTY (piped/captured); a human table
+  on a terminal. Force either with `-o json` / `-o table`.
+- **Diagnostics to stderr**, so stdout is a clean data channel.
+- **Stable exit codes**: `0` ok, `2` usage, `3` auth, `4` not found, `5` API error.
+- **No prompts** — every input is a flag, argument, or stdin.
+
+## Install
+
+```bash
+uv tool install .          # from a clone; or: uvx --from . hyperbrain ...
+# once published: uv tool install hyperspell-brain  /  pipx install hyperspell-brain
+```
+
+The published distribution is `hyperspell-brain` (the bare `hyperbrain` name is
+taken on PyPI by an unrelated project); the installed command is still
+`hyperbrain`.
+
+Once installed, upgrade in place with `hyperbrain update` (a thin wrapper over
+`uv tool upgrade`; `--check` reports whether a newer version exists without
+installing, `--reinstall` forces fresh code from a path install). `update`
+requires a `uv tool` install — if you installed via pipx, upgrade with
+`pipx upgrade hyperspell-brain` instead (the command says so rather than
+silently no-op'ing).
+
+Shell completion is a generator, not an installer — print the script and put it
+where you want:
+
+```bash
+eval "$(hyperbrain completion zsh)"     # this session
+hyperbrain completion zsh >> ~/.zshrc   # persist (bash/zsh/fish supported)
+```
+
+`hyperbrain doctor` prints resolved endpoint, auth state, version, and config
+path with no network call — the first thing to run when something's off.
+
+## For agents
+
+- **`hyperbrain help --agent`** — the whole CLI surface as one compact, low-token
+  markdown doc (commands + auth tiers + contract + recipes), generated from the
+  live command tree. Read it once to self-orient. Scope it with
+  `hyperbrain help --agent <command>`.
+- **`--fields a,b,c`** (global) projects every result to those top-level keys;
+  **`-q/--quiet`** (global) suppresses stdout so you can branch on the exit code
+  alone. Both cut token usage.
+- **`hyperbrain schema`** dumps the full command tree as JSON for programmatic
+  introspection.
+
+## MCP server (Claude Desktop)
+
+Hosts that can't run a CLI or read `CLAUDE.md` — Claude Desktop chief among them —
+reach the brain over MCP instead. The server is an opt-in extra (it pulls
+starlette/uvicorn) and runs over stdio. Its tools come in two tiers, mirroring how
+the product works:
+
+- **Local (fast, no API):** `list_context`, `read_context`, `grep_context` read the
+  synced `~/.hyperspell` summary off disk (also exposed as `hyperbrain://context/...`
+  resources). Read these first.
+- **Source (the full index):** `ask`, `search`, `remember`, `list_memories`,
+  `list_connections` go to the Hyperspell index for source-level detail.
+
+`brain_status` reports what local context exists and the read-local-first workflow.
+
+Crucially, it teaches the host **how** to use the brain. Coding agents learn the
+workflow from the daemon-written `CLAUDE.md` ("read the synced summary first, then
+query"); Claude Desktop never sees that file. So the server detects whether the
+sync daemon's local summary is present and bakes the same ordered methodology into
+its MCP `instructions`, pointing at the actual synced index/sections. A
+`brain_status` tool reports the live state (and the how-to) so a long session can
+re-check after the daemon syncs.
+
+`~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "hyperbrain": {
+      "command": "uvx",
+      "args": ["--from", "hyperspell-brain[mcp]", "hyperbrain-mcp"],
+      "env": { "HYPERSPELL_API_KEY": "hs2-..." }
+    }
+  }
+}
+```
+
+The API key is read from the config `env` (Desktop users never run
+`hyperspell login`). For local dev, point `--from` at the repo path instead of
+the published dist.
+
+## Capability tiers
+
+- **Works with a user API key:** `ask`, `search`, `remember`, `memories`,
+  `connections`, `integrations`, `brain generate`/`latest`/`get`/`progress`.
+- **Needs an admin JWT (not yet wired):** people, skills, config, canonical docs,
+  conflicts, api-keys.
+- **Web-only, no public API (out of scope):** app creation, billing, app settings.
+
+## Design notes & honest limitations
+
+A few things to know — and a few things worth fixing:
+
+- **`ask` needs at least one matching document.** With zero results, the answer
+  path currently returns a server-side 500 instead of a clean empty answer. In an
+  agent loop this reads as a hard error when it really means "no memories matched."
+- **Deep effort is gated.** `medium` / `high` run an agentic loop behind a per-app
+  feature flag. If the flag is off, they *silently* downgrade to a single
+  query-rewrite — so `-e high` isn't always doing what it says. Silent downgrade is
+  a trust wart for an agent reasoning about cost vs. quality; it should be loud.
+- **Curation is the real product.** Once agents `remember` autonomously, brain
+  quality becomes a governance problem — indiscriminate ingestion makes a junk
+  drawer, not a brain. The interesting question isn't "can agents write to it" but
+  "what's *true* when sources disagree." That's the canonical-docs / conflicts
+  machinery, and it's where the moat actually is.
+- **`hyperbrain` and the daemon will likely converge.** They share `~/.hyperspell` and
+  half a worldview (both even have `search`). Today they're two tools — passive sync
+  (`hyperspell`) and active query (`hyperbrain`) — but one binary doing both is the
+  probable end state.

hyperspell_brain-0.4.0/README.md

@@ -0,0 +1,202 @@
+# hyperbrain — agent-first CLI for the Hyperspell company brain
+
+Hyperspell is the brain for your business — the memory layer that unifies
+everything your company knows. `hyperbrain` is the command line into it: one verb
+that humans *and* agents use to query, write, and synthesize that memory.
+Structured JSON by default, pipe-friendly, no interactive prompts required.
+
+```bash
+hyperbrain ask "what's our deployment strategy?"      # synthesized answer + sources
+hyperbrain search "rds proxy" --source slack -n 5     # ranked documents, no synthesis
+echo "remember this" | hyperbrain remember            # write knowledge in
+hyperbrain brain generate                             # (re)build the company-brain tree
+hyperbrain memories status                            # indexing progress per source
+hyperbrain schema                                     # dump the command tree as JSON
+```
+
+## Why this exists
+
+If agents are the primary consumer, why a CLI and not just the API? Because the
+CLI is the **universal adapter**. Any agent that can spawn a shell — Claude Code,
+Cursor, a cron job, an autonomous worker you haven't built yet — can use `hyperbrain`
+with zero bespoke integration. No protocol to implement, no server to run, no SDK
+to vendor. Where MCP says "speak this protocol," `hyperbrain` says "here's a verb."
+
+It's best understood as one half of a pair:
+
+- **Passive context** — the sync daemon writes the synthesized company brain into
+  `~/.hyperspell/` and injects it into every agent's `CLAUDE.md` / `AGENTS.md` /
+  `.cursorrules`. Agents *start* with company context without asking.
+- **Active query** — when the synced summary isn't enough, the agent calls `hyperbrain`
+  to go deeper on demand.
+
+Neither alone is the point: the summary is cheap but shallow, `hyperbrain ask` is deep
+but costs a round-trip. Together, an agent has a free baseline and an escape hatch.
+
+And note the framing: this is a **brain / memory layer**, not retrieval-as-a-service.
+Anyone can do vector search. The value — and the hard part — is keeping a *living,
+curated, coherent* company memory that's current. `hyperbrain brain generate` (synthesis) and
+`hyperbrain remember` (write-back) point at that; raw `search` is just the primitive
+underneath.
+
+## How it's used best
+
+**The highest-leverage move is to register `hyperbrain` as a tool your agents can call**,
+and let them decide when to consult company memory. `hyperbrain schema` exists precisely
+so an agent can introspect every capability as JSON.
+
+Pick the right verb and effort for the job:
+
+| Want | Command | Why |
+|---|---|---|
+| A grounded answer | `hyperbrain ask "…"` | synthesizes + cites; defaults to **all connected sources** |
+| Raw material for another tool | `hyperbrain search "…"` | ranked docs, no LLM — the composable primitive |
+| Speed | `-e minimal` / `low` | verbatim retrieval, or a single LLM query-rewrite |
+| Genuinely multi-hop questions | `-e medium` / `high` | agentic refinement loop (up to 3 / 6 rounds) |
+
+Lean into composability — this is where it beats a UI:
+
+```bash
+hyperbrain ask "what's our deploy process?" -o json | jq -r .answer   # clean text for a prompt
+hyperbrain search "rds proxy" --source slack -n 20 | jq '.documents[].title'
+hyperbrain schema | jq                                                # discover every capability
+```
+
+**Close the loop.** A brain only gets smarter if knowledge flows back in. Treat
+`remember` as a habit — decisions, postmortems, the "why" behind a choice — so future
+queries (by humans *or* agents) surface it:
+
+```bash
+echo "Decision: standardizing on X because Y" | hyperbrain remember --title "arch decision"
+```
+
+Rule of thumb: scope tight (`--source`, low effort) for speed and precision; go broad
+and high-effort only for hard, cross-source questions. The UI *shows* you the brain —
+the CLI lets your agents **think with it**.
+
+## Auth
+
+Reuses the sync daemon's `~/.hyperspell/config.toml` — if you've run
+`hyperspell login` or `hyperspell install`, `hyperbrain` just works. Otherwise pass
+`--api-key` or set `HYPERSPELL_API_KEY` (a long-lived API key or a device JWT).
+
+Precedence: flags > environment > `~/.hyperspell/config.toml` > defaults.
+
+## Agent-first contract
+
+- **JSON by default** to stdout when not a TTY (piped/captured); a human table
+  on a terminal. Force either with `-o json` / `-o table`.
+- **Diagnostics to stderr**, so stdout is a clean data channel.
+- **Stable exit codes**: `0` ok, `2` usage, `3` auth, `4` not found, `5` API error.
+- **No prompts** — every input is a flag, argument, or stdin.
+
+## Install
+
+```bash
+uv tool install .          # from a clone; or: uvx --from . hyperbrain ...
+# once published: uv tool install hyperspell-brain  /  pipx install hyperspell-brain
+```
+
+The published distribution is `hyperspell-brain` (the bare `hyperbrain` name is
+taken on PyPI by an unrelated project); the installed command is still
+`hyperbrain`.
+
+Once installed, upgrade in place with `hyperbrain update` (a thin wrapper over
+`uv tool upgrade`; `--check` reports whether a newer version exists without
+installing, `--reinstall` forces fresh code from a path install). `update`
+requires a `uv tool` install — if you installed via pipx, upgrade with
+`pipx upgrade hyperspell-brain` instead (the command says so rather than
+silently no-op'ing).
+
+Shell completion is a generator, not an installer — print the script and put it
+where you want:
+
+```bash
+eval "$(hyperbrain completion zsh)"     # this session
+hyperbrain completion zsh >> ~/.zshrc   # persist (bash/zsh/fish supported)
+```
+
+`hyperbrain doctor` prints resolved endpoint, auth state, version, and config
+path with no network call — the first thing to run when something's off.
+
+## For agents
+
+- **`hyperbrain help --agent`** — the whole CLI surface as one compact, low-token
+  markdown doc (commands + auth tiers + contract + recipes), generated from the
+  live command tree. Read it once to self-orient. Scope it with
+  `hyperbrain help --agent <command>`.
+- **`--fields a,b,c`** (global) projects every result to those top-level keys;
+  **`-q/--quiet`** (global) suppresses stdout so you can branch on the exit code
+  alone. Both cut token usage.
+- **`hyperbrain schema`** dumps the full command tree as JSON for programmatic
+  introspection.
+
+## MCP server (Claude Desktop)
+
+Hosts that can't run a CLI or read `CLAUDE.md` — Claude Desktop chief among them —
+reach the brain over MCP instead. The server is an opt-in extra (it pulls
+starlette/uvicorn) and runs over stdio. Its tools come in two tiers, mirroring how
+the product works:
+
+- **Local (fast, no API):** `list_context`, `read_context`, `grep_context` read the
+  synced `~/.hyperspell` summary off disk (also exposed as `hyperbrain://context/...`
+  resources). Read these first.
+- **Source (the full index):** `ask`, `search`, `remember`, `list_memories`,
+  `list_connections` go to the Hyperspell index for source-level detail.
+
+`brain_status` reports what local context exists and the read-local-first workflow.
+
+Crucially, it teaches the host **how** to use the brain. Coding agents learn the
+workflow from the daemon-written `CLAUDE.md` ("read the synced summary first, then
+query"); Claude Desktop never sees that file. So the server detects whether the
+sync daemon's local summary is present and bakes the same ordered methodology into
+its MCP `instructions`, pointing at the actual synced index/sections. A
+`brain_status` tool reports the live state (and the how-to) so a long session can
+re-check after the daemon syncs.
+
+`~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "hyperbrain": {
+      "command": "uvx",
+      "args": ["--from", "hyperspell-brain[mcp]", "hyperbrain-mcp"],
+      "env": { "HYPERSPELL_API_KEY": "hs2-..." }
+    }
+  }
+}
+```
+
+The API key is read from the config `env` (Desktop users never run
+`hyperspell login`). For local dev, point `--from` at the repo path instead of
+the published dist.
+
+## Capability tiers
+
+- **Works with a user API key:** `ask`, `search`, `remember`, `memories`,
+  `connections`, `integrations`, `brain generate`/`latest`/`get`/`progress`.
+- **Needs an admin JWT (not yet wired):** people, skills, config, canonical docs,
+  conflicts, api-keys.
+- **Web-only, no public API (out of scope):** app creation, billing, app settings.
+
+## Design notes & honest limitations
+
+A few things to know — and a few things worth fixing:
+
+- **`ask` needs at least one matching document.** With zero results, the answer
+  path currently returns a server-side 500 instead of a clean empty answer. In an
+  agent loop this reads as a hard error when it really means "no memories matched."
+- **Deep effort is gated.** `medium` / `high` run an agentic loop behind a per-app
+  feature flag. If the flag is off, they *silently* downgrade to a single
+  query-rewrite — so `-e high` isn't always doing what it says. Silent downgrade is
+  a trust wart for an agent reasoning about cost vs. quality; it should be loud.
+- **Curation is the real product.** Once agents `remember` autonomously, brain
+  quality becomes a governance problem — indiscriminate ingestion makes a junk
+  drawer, not a brain. The interesting question isn't "can agents write to it" but
+  "what's *true* when sources disagree." That's the canonical-docs / conflicts
+  machinery, and it's where the moat actually is.
+- **`hyperbrain` and the daemon will likely converge.** They share `~/.hyperspell` and
+  half a worldview (both even have `search`). Today they're two tools — passive sync
+  (`hyperspell`) and active query (`hyperbrain`) — but one binary doing both is the
+  probable end state.

hyperspell_brain-0.4.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+# Distribution name is `hyperspell-brain`, not `hyperbrain`: the bare
+# `hyperbrain` name is taken on PyPI by an unrelated 2020 project. The console
+# script stays `hyperbrain` (see [project.scripts]) and the import package stays
+# `hyperbrain` (see tool.hatch.build) — only the published dist name changes.
+name = "hyperspell-brain"
+version = "0.4.0"
+description = "hyperbrain — an agent-first CLI for the Hyperspell company brain"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Hyperspell", email = "hello@hyperspell.com" }]
+dependencies = [
+    "hyperspell>=0.36,<1",
+    "typer>=0.12,<1",
+    "httpx>=0.27,<1",
+]
+
+# The MCP server (for Claude Desktop and other MCP hosts) is opt-in: it pulls
+# starlette/uvicorn/etc., which the common CLI install doesn't need. Install
+# `hyperspell-brain[mcp]` to get the `hyperbrain-mcp` entry point.
+[project.optional-dependencies]
+mcp = ["mcp>=1.28,<2"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8,<9",
+    "mcp>=1.28,<2",  # the MCP tests import hyperbrain.mcp, which needs the extra
+]
+
+[project.scripts]
+hyperbrain = "hyperbrain.cli:app"
+hyperbrain-mcp = "hyperbrain.mcp:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hyperbrain"]
+
+[tool.ruff]
+line-length = 100

hyperspell_brain-0.4.0/src/hyperbrain/__init__.py

@@ -0,0 +1,3 @@
+"""hyperbrain — an agent-first CLI for the Hyperspell company brain."""
+
+__version__ = "0.4.0"

hyperspell_brain-0.4.0/src/hyperbrain/cli.py

@@ -0,0 +1,141 @@
+"""hyperbrain — agent-first CLI for the Hyperspell company brain.
+
+Root command: wires global options into a per-invocation AppCtx, then dispatches
+to the command modules. Designed so an agent can call any subcommand
+non-interactively and parse JSON from stdout.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import typer
+
+from . import __version__, config
+from .context import AppCtx
+from .output import FORMAT_OPTION, Format, emit, pick, set_output_options
+from .commands import api as api_cmd
+from .commands import ask as ask_cmd
+from .commands import auth as auth_cmd
+from .commands import brain as brain_cmd
+from .commands import completion as completion_cmd
+from .commands import config as config_cmd
+from .commands import connections as connections_cmd
+from .commands import doctor as doctor_cmd
+from .commands import guide as guide_cmd
+from .commands import integrations as integrations_cmd
+from .commands import login as login_cmd
+from .commands import memories as memories_cmd
+from .commands import remember as remember_cmd
+from .commands import search as search_cmd
+from .commands import structure as structure_cmd
+from .commands import update as update_cmd
+
+app = typer.Typer(
+    name="hyperbrain",
+    help="Agent-first CLI for the Hyperspell company brain. JSON by default; pipe-friendly.",
+    no_args_is_help=True,
+    add_completion=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def _version(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    api_key: Optional[str] = typer.Option(
+        None, "--api-key", envvar="HYPERSPELL_API_KEY", help="API key (or device JWT)."
+    ),
+    api_url: Optional[str] = typer.Option(
+        None, "--api-url", envvar="HYPERSPELL_BASE_URL", help="API base URL."
+    ),
+    as_user: Optional[str] = typer.Option(
+        None, "--as-user", help="Act as this user (X-As-User; API-key auth only)."
+    ),
+    output_format: Format = typer.Option(
+        Format.AUTO,
+        "--format",
+        "-o",
+        help="Output format: auto (table on TTY, else json), json, table.",
+    ),
+    fields: Optional[str] = typer.Option(
+        None,
+        "--fields",
+        help="Comma-separated top-level keys to keep in the output (token economy).",
+    ),
+    quiet: bool = typer.Option(
+        False,
+        "--quiet",
+        "-q",
+        help="Suppress the stdout data channel; branch on the exit code instead.",
+    ),
+    _v: bool = typer.Option(
+        False, "--version", callback=_version, is_eager=True, help="Show version and exit."
+    ),
+) -> None:
+    """Resolve credentials/endpoint once and stash them for subcommands."""
+    set_output_options(fields=fields, quiet=quiet)
+    ctx.obj = AppCtx(
+        resolved=config.resolve(api_key=api_key, api_url=api_url, as_user=as_user),
+        fmt=output_format,
+    )
+
+
+# Top-level verbs.
+app.command()(login_cmd.login)
+app.command()(ask_cmd.ask)
+app.command()(search_cmd.search)
+app.command()(remember_cmd.remember)
+app.command(name="api")(api_cmd.api)
+app.command()(update_cmd.update)
+app.command()(doctor_cmd.doctor)
+app.command()(completion_cmd.completion)
+app.command(name="help")(guide_cmd.help)
+
+# Grouped nouns.
+app.add_typer(memories_cmd.app, name="memories")
+app.add_typer(connections_cmd.app, name="connections")
+app.add_typer(integrations_cmd.app, name="integrations")
+app.add_typer(brain_cmd.app, name="brain")
+app.add_typer(structure_cmd.app, name="structure")
+app.add_typer(config_cmd.app, name="config")
+app.add_typer(auth_cmd.app, name="auth")
+
+
+def _describe(cmd: Any, name: str) -> dict[str, Any]:
+    """Recursively describe a click command tree using duck-typing (no click import)."""
+    node: dict[str, Any] = {"name": name, "help": (getattr(cmd, "help", "") or "").strip()}
+    params = []
+    for p in getattr(cmd, "params", []):
+        kind = getattr(p, "param_type_name", "parameter")  # 'option' | 'argument'
+        entry: dict[str, Any] = {"name": p.name, "kind": kind, "required": bool(p.required)}
+        if kind == "option":
+            entry["flags"] = list(getattr(p, "opts", []))
+            entry["help"] = getattr(p, "help", "") or ""
+        params.append(entry)
+    if params:
+        node["params"] = params
+    subcommands = getattr(cmd, "commands", None)  # dict on click Groups
+    if isinstance(subcommands, dict):
+        node["commands"] = [_describe(sub, sub_name) for sub_name, sub in subcommands.items()]
+    return node
+
+
+@app.command()
+def schema(
+    ctx: typer.Context,
+    fmt: Optional[Format] = FORMAT_OPTION,
+) -> None:
+    """Dump the full command tree as JSON, so an agent can introspect capabilities."""
+    root = typer.main.get_command(app)
+    emit(_describe(root, "hyperbrain"), pick(ctx, fmt))
+
+
+if __name__ == "__main__":
+    app()