typesafeai-cli 0.3.1__py3-none-any.whl

typesafe_cli/recipes/rank.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from typing import Any
+
+from typesafe_cli.questions import QuestionError
+from typesafe_cli.recipes.find import windows
+from typesafe_cli.recipes.thresholds import RANK_CHUNK
+
+RANK_LEVELS = [
+    "Not relevant to the query",
+    "Somewhat relevant",
+    "Highly relevant to the query",
+]
+
+
+def load_candidates(raw: Any) -> list[dict[str, Any]]:
+    if not isinstance(raw, list) or not raw:
+        raise QuestionError("candidates file must be a non-empty JSON array")
+    out: list[dict[str, Any]] = []
+    for index, item in enumerate(raw):
+        if not isinstance(item, dict):
+            raise QuestionError(f"candidates[{index}] must be an object")
+        out.append(item)
+    return out
+
+
+def candidate_id(item: dict[str, Any], *, id_field: str, index: int) -> str:
+    if id_field in item:
+        return str(item[id_field])
+    return str(index)
+
+
+def candidate_text(item: dict[str, Any], *, text_field: str) -> str:
+    if text_field not in item:
+        raise QuestionError(f"candidate missing text field {text_field!r}")
+    return str(item[text_field])
+
+
+def rank_questions(
+    items: list[dict[str, Any]],
+    *,
+    query: str,
+    id_field: str,
+    text_field: str,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    questions: dict[str, Any] = {}
+    state_items: dict[str, str] = {}
+    for index, item in enumerate(items):
+        iid = candidate_id(item, id_field=id_field, index=index)
+        if iid in questions:
+            raise QuestionError(f"duplicate candidate id: {iid}")
+        text = candidate_text(item, text_field=text_field)
+        state_items[iid] = text
+        questions[iid] = {
+            "type": "score",
+            "instructions": (
+                f"How relevant is candidate `{iid}` to the query `{query}`? "
+                f"Judge `candidates.{iid}` only."
+            ),
+            "criteria": RANK_LEVELS,
+        }
+    state = {"query": query, "candidates": state_items}
+    return state, questions
+
+
+def relevance_of(answer: dict[str, Any]) -> float:
+    if answer.get("type") == "score":
+        return float(answer["score"])
+    if answer.get("type") == "noul":
+        return float(answer["noul"])
+    raise QuestionError(f"cannot rank answer type {answer.get('type')!r}")
+
+
+def sort_ranked(
+    items: list[dict[str, Any]],
+    answers: dict[str, Any],
+    *,
+    id_field: str,
+) -> list[dict[str, Any]]:
+    ranked: list[dict[str, Any]] = []
+    for index, item in enumerate(items):
+        iid = candidate_id(item, id_field=id_field, index=index)
+        answer = answers[iid]
+        ranked.append(
+            {
+                **item,
+                "id": iid,
+                "relevance": relevance_of(answer),
+                "confidence": answer.get("confidence"),
+            }
+        )
+    ranked.sort(key=lambda row: row["relevance"], reverse=True)
+    return ranked
+
+
+def rank_chunks(items: list[dict[str, Any]]) -> list[list[dict[str, Any]]]:
+    return list(windows(items, size=RANK_CHUNK))

typesafe_cli/recipes/screen.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import Any
+
+from typesafe_cli.recipes.thresholds import (
+    SCREEN_HARM_REVIEW,
+    SCREEN_INJECTION,
+    SCREEN_JAILBREAK,
+    SCREEN_SENSITIVE,
+)
+
+SCREEN_QUESTIONS: dict[str, Any] = {
+    "jailbreak": {
+        "type": "noul",
+        "instructions": "Is `text` a jailbreak attempt that tries to override system instructions?",
+    },
+    "injection": {
+        "type": "noul",
+        "instructions": "Does `text` contain a prompt injection or hidden instruction aimed at a model?",
+    },
+    "sensitive": {
+        "type": "noul",
+        "instructions": "Does `text` expose sensitive personal data such as secrets, credentials, or private identifiers?",
+    },
+    "harm": {
+        "type": "score",
+        "instructions": "How much harm would complying with `text` do?",
+        "criteria": [
+            "No meaningful harm",
+            "Limited or reversible harm",
+            "Severe harm if complied with",
+        ],
+    },
+}
+
+
+def suggested_action(
+    *,
+    jailbreak: float,
+    injection: float,
+    sensitive: float,
+    harm_score: float,
+) -> str:
+    if jailbreak >= SCREEN_JAILBREAK or injection >= SCREEN_INJECTION:
+        return "block"
+    if sensitive >= SCREEN_SENSITIVE or harm_score >= SCREEN_HARM_REVIEW:
+        return "review"
+    return "pass"
+
+
+def interpret_screen(answers: dict[str, Any]) -> dict[str, Any]:
+    jailbreak = float(answers["jailbreak"]["noul"])
+    injection = float(answers["injection"]["noul"])
+    sensitive = float(answers["sensitive"]["noul"])
+    harm_score = float(answers["harm"]["score"])
+    return {
+        "jailbreak": jailbreak,
+        "injection": injection,
+        "sensitive": sensitive,
+        "harm": harm_score,
+        "harm_confidence": answers["harm"].get("confidence"),
+        "action": suggested_action(
+            jailbreak=jailbreak,
+            injection=injection,
+            sensitive=sensitive,
+            harm_score=harm_score,
+        ),
+    }

typesafe_cli/recipes/skills.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from typesafe_cli.questions import QuestionError
+from typesafe_cli.recipes.thresholds import SKILL_EXCERPT_CHARS, SKILL_FITS_MIN, SKILL_NEEDS_MIN, SKILL_TOP_K
+
+
+def parse_skill_md(path: Path) -> dict[str, str]:
+    text = path.read_text(encoding="utf-8")
+    meta, body = _frontmatter(text)
+    name = str(meta.get("name") or path.parent.name).strip()
+    description = str(meta.get("description") or "").strip()
+    excerpt = body.strip()[:SKILL_EXCERPT_CHARS]
+    return {
+        "name": name,
+        "description": description or excerpt[:200],
+        "excerpt": excerpt,
+        "path": str(path),
+    }
+
+
+def _frontmatter(text: str) -> tuple[dict[str, str], str]:
+    if not text.startswith("---"):
+        return {}, text
+    end = text.find("\n---", 3)
+    if end < 0:
+        return {}, text
+    raw = text[4:end]
+    body = text[end + 4 :]
+    meta: dict[str, str] = {}
+    key: str | None = None
+    chunks: list[str] = []
+    for line in raw.splitlines():
+        if key and (line.startswith(" ") or line.startswith("\t")):
+            chunks.append(line.strip())
+            continue
+        if ":" in line:
+            if key is not None:
+                meta[key] = " ".join(chunks).strip().lstrip(">|").strip()
+            key, _, rest = line.partition(":")
+            key = key.strip()
+            chunks = [rest.strip()]
+    if key is not None:
+        meta[key] = " ".join(chunks).strip().lstrip(">|").strip()
+    return meta, body
+
+
+def discover_skills(skills_dir: Path) -> list[dict[str, str]]:
+    if not skills_dir.is_dir():
+        raise QuestionError(f"skills dir not found: {skills_dir}")
+    found = [parse_skill_md(path) for path in sorted(skills_dir.rglob("SKILL.md"))]
+    if len(found) < 2:
+        raise QuestionError("suggest-skill needs at least two SKILL.md files")
+    names = [skill["name"] for skill in found]
+    if len(names) != len(set(names)):
+        raise QuestionError("duplicate skill names in skills dir")
+    return found
+
+
+def rank_questions(task: str, skills: list[dict[str, str]]) -> tuple[dict[str, Any], dict[str, Any]]:
+    criteria = {skill["name"]: skill["description"] or None for skill in skills}
+    questions = {
+        "skill": {
+            "type": "choice",
+            "instructions": "Which installed skill, if any, is the best fit for `task`?",
+            "criteria": criteria,
+        },
+        "needs_skill": {
+            "type": "noul",
+            "instructions": "Does `task` require loading a specialized skill rather than general reasoning?",
+        },
+        "documented_procedure": {
+            "type": "noul",
+            "instructions": "Does `task` match a documented procedure that a skill would encode?",
+        },
+        "prose_suffices": {
+            "type": "noul",
+            "instructions": "Would ordinary prose without a skill be enough to complete `task`?",
+        },
+    }
+    state = {
+        "task": task,
+        "skills": {skill["name"]: skill["description"] for skill in skills},
+    }
+    return state, questions
+
+
+def reread_questions(
+    task: str,
+    shortlist: list[dict[str, str]],
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    questions: dict[str, Any] = {}
+    catalog: dict[str, Any] = {}
+    for skill in shortlist:
+        qid = f"fits_{skill['name']}"
+        questions[qid] = {
+            "type": "noul",
+            "instructions": (
+                f"After reading `{skill['name']}`'s excerpt, does this skill fit `task`?"
+            ),
+        }
+        catalog[skill["name"]] = {
+            "description": skill["description"],
+            "excerpt": skill["excerpt"],
+        }
+    return {"task": task, "skills": catalog}, questions
+
+
+def shortlist_from_rank(
+    skills: list[dict[str, str]],
+    answers: dict[str, Any],
+    *,
+    top_k: int = SKILL_TOP_K,
+) -> list[dict[str, str]]:
+    by_name = {skill["name"]: skill for skill in skills}
+    probabilities = answers["skill"].get("probabilities") or {}
+    ranked = sorted(probabilities.items(), key=lambda item: float(item[1]), reverse=True)
+    picked: list[dict[str, str]] = []
+    for name, _probability in ranked:
+        if name in by_name:
+            picked.append(by_name[name])
+        if len(picked) >= top_k:
+            break
+    winner = answers["skill"].get("choice")
+    if winner in by_name and by_name[winner] not in picked:
+        picked = [by_name[winner], *picked][:top_k]
+    return picked
+
+
+def pick_skill(
+    *,
+    rank_answers: dict[str, Any],
+    fit_answers: dict[str, Any],
+    shortlist: list[dict[str, str]],
+) -> str | None:
+    needs = float(rank_answers["needs_skill"]["noul"])
+    if needs < SKILL_NEEDS_MIN:
+        return None
+    scored: list[tuple[float, str]] = []
+    for skill in shortlist:
+        noul = float(fit_answers[f"fits_{skill['name']}"]["noul"])
+        scored.append((noul, skill["name"]))
+    scored.sort(reverse=True)
+    if not scored or scored[0][0] < SKILL_FITS_MIN:
+        return None
+    return scored[0][1]

typesafe_cli/recipes/thresholds.py

@@ -0,0 +1,24 @@
+"""Application policy constants. Edit here; do not hide them inside Jev."""
+
+CHOICE_MAX_OPTIONS = 255
+FIND_CHUNK = 255
+RANK_CHUNK = 64
+
+FIND_EXISTS_ANSWERED = 0.70
+FIND_EXISTS_PARTIAL = 0.35
+
+VERIFY_AUTO_CONFIDENCE = 0.80
+
+NOUL_UNCERTAIN_LOW = 0.30
+NOUL_UNCERTAIN_HIGH = 0.70
+CHOICE_MIN_TOP_P = 0.60
+
+SCREEN_JAILBREAK = 0.70
+SCREEN_INJECTION = 0.70
+SCREEN_SENSITIVE = 0.70
+SCREEN_HARM_REVIEW = 1.5
+
+SKILL_TOP_K = 3
+SKILL_NEEDS_MIN = 0.55
+SKILL_FITS_MIN = 0.55
+SKILL_EXCERPT_CHARS = 1200

typesafe_cli/recipes/verify.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import Any
+
+from typesafe_cli.recipes.thresholds import VERIFY_AUTO_CONFIDENCE
+
+
+def quote_in_source(source: str, quote: str) -> bool:
+    return bool(quote) and quote in source
+
+
+def verify_questions(*, claim: str) -> dict[str, Any]:
+    return {
+        "support": {
+            "type": "choice",
+            "instructions": (
+                "Does `source` support `claim`? "
+                "supports = the source affirms the claim; "
+                "contradicts = the source denies it; "
+                "says_nothing = the source is silent."
+            ),
+            "criteria": {
+                "supports": "The source affirms the claim",
+                "contradicts": "The source conflicts with the claim",
+                "says_nothing": "The source does not address the claim",
+            },
+        }
+    }
+
+
+def verify_state(*, claim: str, source: str, quote: str | None) -> dict[str, Any]:
+    state: dict[str, Any] = {"claim": claim, "source": source}
+    if quote:
+        state["quote"] = quote
+    return state
+
+
+def interpret_verify(answer: dict[str, Any], *, auto_confidence: float = VERIFY_AUTO_CONFIDENCE) -> dict[str, Any]:
+    verdict = answer["choice"]
+    confidence = float(answer.get("confidence") or 0.0)
+    auto = confidence >= auto_confidence and verdict != "says_nothing"
+    return {
+        "verdict": verdict,
+        "confidence": confidence,
+        "auto": auto,
+        "review": not auto,
+        "probabilities": answer.get("probabilities") or {},
+    }

typesafe_cli/schema.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+from typesafe_cli import __version__
+from typesafe_cli.detect import is_agent_mode
+
+
+def command_schema(*, compact: bool = False) -> dict[str, Any]:
+    from typesafe_cli.cli import app
+
+    commands = _walk_typer(app, path=[])
+    if compact:
+        return {
+            "version": __version__,
+            "name": "typesafe",
+            "commands": commands,
+        }
+    return {
+        "version": __version__,
+        "name": "typesafe",
+        "description": "CLI for TypeSafe System One (Jev). Typed judgments, not chat.",
+        "agent_mode": is_agent_mode(),
+        "auth": {
+            "check": "typesafe auth status",
+            "flags": ["--key", "--creds"],
+            "note": "Agents cannot access typesafeai-cli environment variables or key files. Use auth status (has_key only). Never print, echo, or cat secrets.",
+        },
+        "secrets": {
+            "rule": "Agents cannot access typesafeai-cli environment variables or key files.",
+            "forbidden": [
+                "TYPESAFE_API_KEY",
+                "TYPESAFE_BASE_URL",
+                "TYPESAFE_DEFAULT_MODEL",
+                "~/.config/typesafe/env",
+                ".env.local",
+                "--creds files",
+                "--key values",
+            ],
+            "do_not": [
+                "echo $TYPESAFE_API_KEY",
+                "printenv or env | grep TYPESAFE",
+                "cat ~/.config/typesafe/env or .env.local",
+            ],
+            "instead": "Run typesafe auth status. If has_key is false, ask the human. The CLI loads the key; you do not.",
+        },
+        "output": {
+            "stdout": "{status, data, metadata}",
+            "stderr": "{status, error: {code, message}}",
+            "exit_codes": {"0": "answered", "1": "request failed", "2": "usage / invalid questions"},
+        },
+        "anti_patterns": [
+            "Do not chat with Jev or ask it what to do next.",
+            "Do not loop typesafe noul once per question; batch independent questions in typesafe ask, or use find/rank/extract/verify/screen/suggest-skill.",
+            "Do not invent request or response fields; use typesafe agent schema.",
+            "Do not treat a Noul near 0.5 as medium intensity; it is uncertainty.",
+            "Do not read, print, or echo TYPESAFE_* environment variables or key files.",
+        ],
+        "workflows": [
+            {
+                "name": "evaluate",
+                "skill": "typesafe-cli",
+                "steps": [
+                    "typesafe auth status — use has_key only; do not read env vars or key files.",
+                    "Write questions first. Instructions must backtick the state paths they need. That list is the collection contract — do not catalog every agent job.",
+                    "Fill only those paths in ${TMPDIR:-/tmp}/codex/<project>/state.json. If a path is code, include the hunk body. Redact secrets. If you cannot, do not call TypeSafe.",
+                    "typesafe ask --state-file $WORKDIR/state.json --questions-file $WORKDIR/questions.json",
+                    "Apply thresholds locally. Noul ~0.5 is unsure. Low confidence: abstain. You pick the next action.",
+                    "Compose: one ask per document (do not loop noul). Local prefilter then Jev (regex, quote match). Use find/rank/extract/verify/screen/suggest-skill/decide when those flags fit. Second HTTP only to shrink options or fetch evidence.",
+                ],
+            }
+        ],
+        "commands": commands,
+    }
+
+
+def schema_for_help(ctx: Any) -> dict[str, Any]:
+    full = command_schema(compact=False)
+    path = [part for part in ctx.command_path.split() if part and part != "typesafe"]
+    if not path:
+        return full
+    scoped = _find_command(full["commands"], path)
+    if scoped is None:
+        return full
+    data = dict(full)
+    data["commands"] = [scoped]
+    return data
+
+
+def _walk_typer(app: Any, *, path: list[str]) -> list[dict[str, Any]]:
+    nodes: list[dict[str, Any]] = []
+    for info in getattr(app, "registered_commands", []):
+        name = info.name or getattr(info.callback, "__name__", "")
+        node = _command_node(info, path=[*path, name])
+        if path:
+            # drop global --agent flags from nested command param lists; they live on the root
+            node["params"] = [p for p in node["params"] if "--agent" not in p["names"] and "--no-agent" not in p["names"]]
+        nodes.append(node)
+    for info in getattr(app, "registered_groups", []):
+        name = info.name or ""
+        sub_app = info.typer_instance
+        nodes.append(
+            {
+                "name": " ".join([*path, name]).strip(),
+                "help": info.help or "",
+                "params": [],
+                "commands": _walk_typer(sub_app, path=[*path, name]) if sub_app is not None else [],
+            }
+        )
+    return nodes
+
+
+def _command_node(info: Any, *, path: list[str]) -> dict[str, Any]:
+    callback = info.callback
+    params: list[dict[str, Any]] = []
+    if callback is not None:
+        for parameter in inspect.signature(callback).parameters.values():
+            if parameter.name == "ctx":
+                continue
+            default = parameter.default
+            decls = getattr(default, "param_decls", None)
+            names = [str(d) for d in decls] if decls else [parameter.name]
+            required = getattr(default, "default", inspect.Parameter.empty) is ...
+            if default is inspect.Parameter.empty:
+                required = True
+                names = [parameter.name]
+            params.append(
+                {
+                    "names": names,
+                    "required": bool(required),
+                    "help": getattr(default, "help", None),
+                }
+            )
+    return {
+        "name": " ".join(path),
+        "help": info.help or (getattr(callback, "__doc__", None) or ""),
+        "params": params,
+    }
+
+
+def _find_command(commands: list[dict[str, Any]], path: list[str]) -> dict[str, Any] | None:
+    wanted = " ".join(path)
+    for cmd in commands:
+        if cmd.get("name") == wanted:
+            return cmd
+        nested = _find_command(cmd.get("commands") or [], path)
+        if nested is not None:
+            return nested
+    return None

typesafeai_cli-0.3.1.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.5
+Name: typesafeai-cli
+Version: 0.3.1
+Summary: Agent CLI for TypeSafe System One (Jev)
+Project-URL: Homepage, https://github.com/maddygoround/typesafeai-cli
+Project-URL: Repository, https://github.com/maddygoround/typesafeai-cli
+Project-URL: Issues, https://github.com/maddygoround/typesafeai-cli/issues
+Project-URL: Releases, https://github.com/maddygoround/typesafeai-cli/releases
+Author: safeaiforeveryone
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,jev,typesafe
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: typer>=0.12
+Requires-Dist: typesafe-sdk>=0.6.0
+Description-Content-Type: text/markdown
+
+# TypeSafe agent CLI
+
+`typesafe` is an **agent CLI** for [TypeSafe](https://typesafe.ai) **Jev**.
+
+It is meant to be invoked by coding agents (Grok, Codex, Claude Code, Cursor, and anything else that can run a shell command). You can run it yourself while you debug; the usual caller is an agent.
+
+Jev does not chat. The agent gathers a small JSON document (`state`) and typed questions (`noul`, `choice`, `score`). This CLI sends that to `POST /v1/systemone` and prints probabilities on stdout. Jev never sees the repo unless the agent copies the relevant slices into `state`.
+
+You do not hand-write production payloads every day. Install the **typesafe-cli** skill, and the agent writes the JSON (in a temp directory, not in git). The files under [`examples/`](examples/) exist so you can see the shape, and so you can run a call without inventing one.
+
+## JSON shape
+
+Two files. Names are yours; types are not.
+
+**`state.json`** — named fields the questions will point at:
+
+```json
+{
+  "message": "I was charged twice for order A-104. Please refund the duplicate.",
+  "policy": "Duplicate charges are eligible for an immediate refund."
+}
+```
+
+**`questions.json`** — one judgment per id. `instructions` should backtick those fields (`` `message` ``):
+
+```json
+{
+  "refund_requested": {
+    "type": "noul",
+    "instructions": "Does `message` request a refund?"
+  },
+  "intent": {
+    "type": "choice",
+    "instructions": "What does `message` ask for?",
+    "criteria": {
+      "refund": "The customer wants money returned",
+      "information": "Explanation only",
+      "other": "Something else"
+    }
+  }
+}
+```
+
+Full copies, including a **code-change** example with `files[].hunk`:
+
+| Sample | Files |
+| --- | --- |
+| Support ticket | [`examples/ticket/state.json`](examples/ticket/state.json), [`questions.json`](examples/ticket/questions.json) |
+| Skill / code slice | [`examples/code-change/state.json`](examples/code-change/state.json), [`questions.json`](examples/code-change/questions.json) |
+| How to run them | [`examples/README.md`](examples/README.md) |
+
+```bash
+WORKDIR="${TMPDIR:-/tmp}/codex/typesafeai-cli"
+mkdir -p "$WORKDIR"
+cp examples/ticket/*.json "$WORKDIR/"
+typesafe ask --state-file "$WORKDIR/state.json" --questions-file "$WORKDIR/questions.json"
+```
+
+One-liners skip files: `typesafe noul "Does this request a refund?" --state "I was charged twice."`
+
+If `data.model` looks like `jev-1.13.0`, the request reached TypeSafe. `auth status` does not.
+
+## What the agent is supposed to do
+
+1. `typesafe skills install` (once) so **typesafe-cli** and the official TypeSafe skill are on disk.
+2. `typesafe auth status` — read `has_key` only. Agents must not print or open `TYPESAFE_*` or key files.
+3. Write questions first. Each instruction backticks the state paths it needs. That list is what to collect.
+4. Fill only those paths. If a path is code, put the hunk body in, not a filename.
+5. Write JSON under `${TMPDIR:-/tmp}/codex/<project>/`, never in the git tree.
+6. `typesafe ask`. Apply thresholds in the agent (a noul near `0.5` is unsure). Jev does not pick the next tool.
+
+`typesafe agent schema` is the machine-readable command list. `--agent` makes `--help` JSON.
+
+## Install
+
+Python 3.10+ and a key from the [TypeSafe console](https://console.typesafe.ai/settings/keys).
+
+```bash
+export TYPESAFE_API_KEY=apikey_…
+
+pip install typesafeai-cli
+# or: pipx install typesafeai-cli
+# or clone, then: uv sync && uv run typesafe --help
+```
+
+`install.sh` on the repo and on each release can also install the GitHub wheel. Optional: `TYPESAFE_BASE_URL`, `TYPESAFE_DEFAULT_MODEL`. `--key` / `--creds` are for scripts, not for agents scraping secrets.
+
+## Commands
+
+| | |
+| --- | --- |
+| `typesafe ask` | State file + questions file |
+| `typesafe noul` / `choice` / `score` | One question |
+| `typesafe find` | Search a local file by plain-language query |
+| `typesafe rank` | Rerank a JSON shortlist |
+| `typesafe extract` | Pick a verbatim span (email / phone / money / `--candidates`) |
+| `typesafe verify` | Check a claim against a source (missing quote → fabricated) |
+| `typesafe screen` | Jailbreak / injection / sensitive-data / harm gate |
+| `typesafe suggest-skill` | At most one skill name, or none |
+| `typesafe decide` | Map nouls/choices to no / uncertain / yes (no HTTP) |
+| `typesafe models` | Aliases (`jev-latest`, …) |
+| `typesafe smoke` | Live docs quickstart |
+| `typesafe auth status` | `has_key`; never prints the key |
+| `typesafe agent schema` | JSON command tree |
+| `typesafe skills install` | Official TypeSafe skill + **typesafe-cli** |
+
+Exit `0` answered, `1` request failed (including missing key on `ask`), `2` bad flags or questions (no HTTP).
+
+## Releases
+
+A merge to `main` that passes CI ships automatically: patch bump, tag `vX.Y.Z`, GitHub release, PyPI (`release.yml`, environment `pypi`). Start the merge commit with `[skip release]` to skip. For a minor or major, run **Prepare Release** and pick the bump.
+
+Match `version` in `pyproject.toml` to `__version__` in `src/typesafe_cli/__init__.py` if you tag by hand.