typesafeai-cli 0.3.2__tar.gz → 0.3.3__tar.gz

{typesafeai_cli-0.3.2 → typesafeai_cli-0.3.3}/.gitignore

@@ -2,6 +2,7 @@
 .env
 PLAN.md
 plan.md
+PHASE3.md
 docs/
 .venv/
 __pycache__/

typesafeai_cli-0.3.3/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.5
+Name: typesafeai-cli
+Version: 0.3.3
+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
+
+CLI for [TypeSafe](https://typesafe.ai) Jev. Run it from a shell, or let an agent run it.
+
+Jev answers `noul`, `choice`, and `score` questions over JSON `state`. It does not chat, and it only sees what you send. Invalid answers fail closed. Unused speculative heads cannot act. Ranked `find` lines are not evidence when the document has no answer.
+
+## Install
+
+Python 3.10+. API key: [TypeSafe console](https://console.typesafe.ai/settings/keys).
+
+```bash
+curl -fsSL https://github.com/maddygoround/typesafeai-cli/releases/latest/download/install.sh | bash
+```
+
+```bash
+pipx install typesafeai-cli
+```
+
+`pip install typesafeai-cli` is the same package.
+
+```bash
+export TYPESAFE_API_KEY=apikey_…
+```
+
+## Usage
+
+`typesafe ask` takes a state file and a questions file. Point each instruction at state with backticks.
+
+```json
+{
+  "message": "I was charged twice for order A-104. Please refund the duplicate.",
+  "policy": "Duplicate charges are eligible for an immediate refund."
+}
+```
+
+```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"
+    }
+  }
+}
+```
+
+[`examples/ticket`](examples/ticket), [`examples/code-change`](examples/code-change), and [`examples/fan-out`](examples/fan-out) are full copies.
+
+```bash
+typesafe ask --state-file state.json --questions-file questions.json
+typesafe noul "Does this request a refund?" --state "I was charged twice."
+typesafe decide --answers-file last.json
+```
+
+Keep those JSON files under `${TMPDIR:-/tmp}/codex/<project>/`. `typesafe skills install` matches `npx skills add`: `--project` (default) or `--global` / `-g`. A TTY asks which. Global also writes a pointer into the user agent file (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, or `~/.grok/rules/typesafe-cli.md`) so investigations load `typesafe`. `typesafe auth status` reports `has_key` and nothing else.
+
+## Commands
+
+| | |
+| --- | --- |
+| `ask` | State file + questions file |
+| `noul` / `choice` / `score` | One question |
+| `find` | Search a file |
+| `rank` | Order a JSON shortlist |
+| `extract` | Pick a span already in the text |
+| `verify` | Check a claim against a source |
+| `screen` | Jailbreak / injection / sensitive-data / harm |
+| `suggest-skill` | At most one skill name |
+| `decide` | Map answers to yes / no / uncertain (no HTTP) |
+| `models` | Model aliases |
+| `smoke` | Live docs quickstart |
+| `auth status` | Whether a key is loaded |
+| `agent schema` | JSON command tree |
+| `skills install` | Official TypeSafe skill + typesafe-cli (`-g` for all projects) |
+
+Exit `0` answered, `1` request failed or invalid answer, `2` bad flags or questions.

typesafeai_cli-0.3.3/README.md

@@ -0,0 +1,83 @@
+# typesafe
+
+CLI for [TypeSafe](https://typesafe.ai) Jev. Run it from a shell, or let an agent run it.
+
+Jev answers `noul`, `choice`, and `score` questions over JSON `state`. It does not chat, and it only sees what you send. Invalid answers fail closed. Unused speculative heads cannot act. Ranked `find` lines are not evidence when the document has no answer.
+
+## Install
+
+Python 3.10+. API key: [TypeSafe console](https://console.typesafe.ai/settings/keys).
+
+```bash
+curl -fsSL https://github.com/maddygoround/typesafeai-cli/releases/latest/download/install.sh | bash
+```
+
+```bash
+pipx install typesafeai-cli
+```
+
+`pip install typesafeai-cli` is the same package.
+
+```bash
+export TYPESAFE_API_KEY=apikey_…
+```
+
+## Usage
+
+`typesafe ask` takes a state file and a questions file. Point each instruction at state with backticks.
+
+```json
+{
+  "message": "I was charged twice for order A-104. Please refund the duplicate.",
+  "policy": "Duplicate charges are eligible for an immediate refund."
+}
+```
+
+```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"
+    }
+  }
+}
+```
+
+[`examples/ticket`](examples/ticket), [`examples/code-change`](examples/code-change), and [`examples/fan-out`](examples/fan-out) are full copies.
+
+```bash
+typesafe ask --state-file state.json --questions-file questions.json
+typesafe noul "Does this request a refund?" --state "I was charged twice."
+typesafe decide --answers-file last.json
+```
+
+Keep those JSON files under `${TMPDIR:-/tmp}/codex/<project>/`. `typesafe skills install` matches `npx skills add`: `--project` (default) or `--global` / `-g`. A TTY asks which. Global also writes a pointer into the user agent file (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, or `~/.grok/rules/typesafe-cli.md`) so investigations load `typesafe`. `typesafe auth status` reports `has_key` and nothing else.
+
+## Commands
+
+| | |
+| --- | --- |
+| `ask` | State file + questions file |
+| `noul` / `choice` / `score` | One question |
+| `find` | Search a file |
+| `rank` | Order a JSON shortlist |
+| `extract` | Pick a span already in the text |
+| `verify` | Check a claim against a source |
+| `screen` | Jailbreak / injection / sensitive-data / harm |
+| `suggest-skill` | At most one skill name |
+| `decide` | Map answers to yes / no / uncertain (no HTTP) |
+| `models` | Model aliases |
+| `smoke` | Live docs quickstart |
+| `auth status` | Whether a key is loaded |
+| `agent schema` | JSON command tree |
+| `skills install` | Official TypeSafe skill + typesafe-cli (`-g` for all projects) |
+
+Exit `0` answered, `1` request failed or invalid answer, `2` bad flags or questions.

typesafeai_cli-0.3.3/examples/README.md

@@ -0,0 +1,12 @@
+| Directory | |
+| --- | --- |
+| [ticket/](ticket/) | Support message, refund / intent / frustration |
+| [code-change/](code-change/) | A skill hunk, whether the change needs real code in state |
+| [fan-out/](fan-out/) | One operation Choice plus speculative `*_target` heads |
+
+```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"
+```

typesafeai_cli-0.3.3/examples/fan-out/questions.json

@@ -0,0 +1,28 @@
+{
+  "operation": {
+    "type": "choice",
+    "instructions": "Given `task` and `files[0].hunk`, what should the agent do next?",
+    "criteria": {
+      "EDIT": "Change the skill text so agents attach real code slices",
+      "ASK": "Ask the human before changing anything",
+      "SKIP": "Do nothing; the skill is already clear",
+      "abstain": "Not enough in state to decide"
+    }
+  },
+  "edit_target": {
+    "type": "choice",
+    "instructions": "If the next operation is EDIT, which observed hunk should be changed? This question chooses only a target; another question chooses the operation.",
+    "criteria": {
+      "files[0]": "The skill hunk already in `files[0].hunk`",
+      "none": "No offered hunk should be edited"
+    }
+  },
+  "ask_target": {
+    "type": "choice",
+    "instructions": "If the next operation is ASK, what should we ask the human? This question chooses only a target; another question chooses the operation.",
+    "criteria": {
+      "scope": "Ask whether the skill should stay questions-first",
+      "none": "Do not ask"
+    }
+  }
+}

typesafeai_cli-0.3.3/examples/fan-out/state.json

@@ -0,0 +1,10 @@
+{
+  "task": "A coding agent is about to edit a skill. Decide the next operation, then which hunk to touch if the operation is EDIT.",
+  "files": [
+    {
+      "path": "src/typesafe_cli/data/typesafe-cli/SKILL.md",
+      "line_range": "50-74",
+      "hunk": "If a path is code (`files[0].hunk`), the value must be the slice (path + line range + body), not a filename and not \"see the PR.\""
+    }
+  ]
+}

{typesafeai_cli-0.3.2 → typesafeai_cli-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "typesafeai-cli"
-version = "0.3.2"
+version = "0.3.3"
 description = "Agent CLI for TypeSafe System One (Jev)"
 readme = "README.md"
 license = "MIT"

typesafeai_cli-0.3.3/src/typesafe_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.3"

typesafeai_cli-0.3.3/src/typesafe_cli/agent_files.py

@@ -0,0 +1,69 @@
+"""Idempotent TypeSafe pointer in the user's global agent files (not the repo)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+START = "<!-- typesafe-cli:start -->"
+END = "<!-- typesafe-cli:end -->"
+
+SNIPPET = """<!-- typesafe-cli:start -->
+## TypeSafe CLI
+
+When the user asks to investigate, triage, verify a claim, rank options, extract a span, screen a message, route a task, or make a typed yes/no or score judgment (Jev, noul, choice, TypeSafe), follow the **typesafe-cli** skill and run `typesafe`. Collect only the named state first. Do not curl TypeSafe.
+<!-- typesafe-cli:end -->
+"""
+
+
+def global_agent_paths(*, home: Path, agent: str) -> list[Path]:
+    """Home-level files each agent loads on every session.
+
+    Same split as `npx skills add -g`: user config, not the git tree.
+    """
+    claude = home / ".claude" / "CLAUDE.md"
+    codex = home / ".codex" / "AGENTS.md"
+    grok_rule = home / ".grok" / "rules" / "typesafe-cli.md"
+    agents = home / ".agents" / "AGENTS.md"
+    cursor = home / ".cursor" / "AGENTS.md"
+    gemini = home / ".gemini" / "GEMINI.md"
+    by_agent = {
+        "claude-code": [claude],
+        "codex": [codex],
+        "grok": [grok_rule, claude],
+        "cursor": [cursor],
+        "gemini-code": [gemini],
+        "opencode": [agents],
+        "generic-agent": [agents],
+    }
+    if agent in by_agent:
+        return by_agent[agent]
+    existing = [p for p in (claude, codex, grok_rule, agents, cursor, gemini) if p.is_file()]
+    return existing or [grok_rule]
+
+
+def upsert_global_agent_files(*, home: Path, agent: str) -> list[Path]:
+    written: list[Path] = []
+    for path in global_agent_paths(home=home, agent=agent):
+        path.parent.mkdir(parents=True, exist_ok=True)
+        _upsert_snippet(path)
+        written.append(path)
+    return written
+
+
+def _upsert_snippet(path: Path) -> None:
+    body = path.read_text(encoding="utf-8") if path.is_file() else ""
+    block = SNIPPET.strip() + "\n"
+    start = body.find(START)
+    end = body.find(END)
+    if start != -1 and end != -1 and end > start:
+        end += len(END)
+        while end < len(body) and body[end] == "\n":
+            end += 1
+        updated = body[:start].rstrip() + "\n\n" + block + body[end:].lstrip("\n")
+        if not updated.endswith("\n"):
+            updated += "\n"
+    elif body.strip():
+        updated = body.rstrip() + "\n\n" + block
+    else:
+        updated = block
+    path.write_text(updated, encoding="utf-8")

typesafeai_cli-0.3.3/src/typesafe_cli/answers.py

@@ -0,0 +1,86 @@
+"""Fail-closed checks on TypeSafe answers. Invalid JSON is not a decision."""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+
+class AnswerError(ValueError):
+    """The envelope is not a usable typed answer; do not act on it."""
+
+
+def validate_answers(answers: dict[str, Any], *, questions: dict[str, dict[str, Any]] | None = None) -> None:
+    if not isinstance(answers, dict) or not answers:
+        raise AnswerError("Invalid TypeSafe response; no action executed.")
+    questions = questions or {}
+    for qid, answer in answers.items():
+        if not isinstance(qid, str) or not qid or not isinstance(answer, dict):
+            raise AnswerError("Invalid TypeSafe response; no action executed.")
+        qtype = answer.get("type") or (questions.get(qid) or {}).get("type")
+        if qtype == "choice":
+            ids = _choice_ids(qid, answer, questions)
+            _validate_choice(answer, ids)
+        elif qtype == "noul":
+            _validate_noul(answer)
+        elif qtype == "score":
+            _validate_score(answer)
+        else:
+            raise AnswerError("Invalid TypeSafe response; no action executed.")
+
+
+def _choice_ids(qid: str, answer: dict[str, Any], questions: dict[str, dict[str, Any]]) -> set[str]:
+    criteria = (questions.get(qid) or {}).get("criteria")
+    if isinstance(criteria, dict) and criteria:
+        return {str(key) for key in criteria}
+    probabilities = answer.get("probabilities") or {}
+    if isinstance(probabilities, dict) and probabilities:
+        return {str(key) for key in probabilities}
+    raise AnswerError("Invalid TypeSafe response; no action executed.")
+
+
+def _validate_choice(answer: dict[str, Any], ids: set[str]) -> None:
+    try:
+        probabilities = {str(k): v for k, v in dict(answer["probabilities"]).items()}
+        confidence = answer["confidence"]
+        numbers = [*probabilities.values(), confidence]
+        choice = str(answer["choice"])
+        valid = (
+            choice in ids
+            and set(probabilities) == ids
+            and all(isinstance(n, (int, float)) and math.isfinite(n) and 0 <= n <= 1 for n in numbers)
+            and abs(sum(probabilities.values()) - 1) < 0.02
+            and probabilities[choice] >= max(probabilities.values()) - 1e-6
+        )
+    except (KeyError, TypeError, ValueError):
+        valid = False
+    if not valid:
+        raise AnswerError("Invalid TypeSafe response; no action executed.")
+
+
+def _validate_noul(answer: dict[str, Any]) -> None:
+    try:
+        value = answer["noul"]
+        valid = isinstance(value, (int, float)) and math.isfinite(value) and 0 <= value <= 1
+    except (KeyError, TypeError):
+        valid = False
+    if not valid:
+        raise AnswerError("Invalid TypeSafe response; no action executed.")
+
+
+def _validate_score(answer: dict[str, Any]) -> None:
+    try:
+        score = answer["score"]
+        confidence = answer.get("confidence")
+        valid = isinstance(score, (int, float)) and math.isfinite(score)
+        if confidence is not None:
+            valid = (
+                valid
+                and isinstance(confidence, (int, float))
+                and math.isfinite(confidence)
+                and 0 <= confidence <= 1
+            )
+    except (KeyError, TypeError):
+        valid = False
+    if not valid:
+        raise AnswerError("Invalid TypeSafe response; no action executed.")

{typesafeai_cli-0.3.2 → typesafeai_cli-0.3.3}/src/typesafe_cli/cli.py

@@ -25,7 +25,7 @@ app = typer.Typer(
     no_args_is_help=True,
     add_completion=False,
     pretty_exceptions_enable=False,
-    help="Agent CLI for TypeSafe System One (Jev). Typed judgments, not chat. Agents must not read TYPESAFE_* env vars or key files; use typesafe auth status.",
+    help="Agent CLI for TypeSafe System One (Jev). Typed judgments, not chat. Invalid answers fail closed. Agents must not read TYPESAFE_* env vars or key files; use typesafe auth status.",
 )
 
 

{typesafeai_cli-0.3.2 → typesafeai_cli-0.3.3}/src/typesafe_cli/client.py

@@ -4,6 +4,7 @@ from typing import Any
 
 from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
 
+from typesafe_cli.answers import validate_answers
 from typesafe_cli.config import Config
 
 
@@ -87,7 +88,9 @@ def system_one(
             questions=to_sdk_questions(questions),
             model=resolved_model,
         )
-    return answers_to_dict(response)
+    data = answers_to_dict(response)
+    validate_answers(data["answers"], questions=questions)
+    return data
 
 
 def list_models(*, config: Config) -> dict[str, Any]:

{typesafeai_cli-0.3.2 → typesafeai_cli-0.3.3}/src/typesafe_cli/commands/ask.py

@@ -7,6 +7,7 @@ from typing import Any
 import typer
 from typesafe_sdk import TypeSafeError
 
+from typesafe_cli.answers import AnswerError
 from typesafe_cli.client import system_one
 from typesafe_cli.config import load_config
 from typesafe_cli.io import emit_success, fail
@@ -38,6 +39,8 @@ def ask(
 
     try:
         data = system_one(config=config, state=resolved_state, questions=questions, model=model)
+    except AnswerError as exc:
+        fail(code="invalid_answer", message=str(exc), exit_code=1)
     except TypeSafeError as exc:
         fail(code="request", message=str(exc), exit_code=1)
     except Exception as exc:  # noqa: BLE001 — surface SDK/network failures as exit 1
@@ -83,6 +86,8 @@ def run_evaluation(
         fail(code="auth", message="missing TYPESAFE_API_KEY (or --key / --creds)", exit_code=1)
     try:
         data = system_one(config=config, state=state, questions=questions, model=model)
+    except AnswerError as exc:
+        fail(code="invalid_answer", message=str(exc), exit_code=1)
     except TypeSafeError as exc:
         fail(code="request", message=str(exc), exit_code=1)
     except Exception as exc:  # noqa: BLE001

{typesafeai_cli-0.3.2 → typesafeai_cli-0.3.3}/src/typesafe_cli/commands/decide.py

@@ -7,7 +7,7 @@ import typer
 
 from typesafe_cli.io import emit_success, fail
 from typesafe_cli.questions import QuestionError
-from typesafe_cli.recipes.decide import apply_decide, extract_answers, parse_noul_band
+from typesafe_cli.recipes.decide import apply_decide, decide_action, extract_answers, parse_noul_band
 from typesafe_cli.recipes.thresholds import CHOICE_MIN_TOP_P, NOUL_UNCERTAIN_HIGH, NOUL_UNCERTAIN_LOW
 
 
@@ -34,9 +34,14 @@ def decide(
         decisions = apply_decide(answers, noul_low=low, noul_high=high, choice_min_p=choice_min_p)
     except (OSError, json.JSONDecodeError, QuestionError) as exc:
         fail(code="usage", message=str(exc), exit_code=2)
+    gate = decide_action(decisions)
     emit_success(
         data={
             "decisions": decisions,
+            "active": gate["active"],
+            "ignored": gate["ignored"],
+            "action": gate["action"],
+            "needs_verify": gate["needs_verify"],
             "policy": {"noul_band": [low, high], "choice_min_p": choice_min_p},
         },
         command="decide",

{typesafeai_cli-0.3.2 → typesafeai_cli-0.3.3}/src/typesafe_cli/commands/eval.py

@@ -5,6 +5,7 @@ from typing import Any
 
 from typesafe_sdk import TypeSafeError
 
+from typesafe_cli.answers import AnswerError
 from typesafe_cli.client import system_one
 from typesafe_cli.config import load_config
 from typesafe_cli.io import fail
@@ -31,6 +32,8 @@ def call_system_one(
     config = ready_config(key=key, creds=creds, model=model)
     try:
         return system_one(config=config, state=state, questions=questions, model=model)
+    except AnswerError as exc:
+        fail(code="invalid_answer", message=str(exc), exit_code=1)
     except TypeSafeError as exc:
         fail(code="request", message=str(exc), exit_code=1)
     except Exception as exc:  # noqa: BLE001

{typesafeai_cli-0.3.2 → typesafeai_cli-0.3.3}/src/typesafe_cli/commands/find.py

@@ -45,6 +45,7 @@ def find(
             "file": str(file),
             "verdict": merged["verdict"],
             "exists": merged["exists"],
+            "usable": merged["usable"],
             "lines": merged["query_lines"][:20],
             "model": merged["model"],
             "usage": merged["usage"],

{typesafeai_cli-0.3.2 → typesafeai_cli-0.3.3}/src/typesafe_cli/commands/skills.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import sys
 import urllib.error
 import urllib.request
 from importlib.resources import files
@@ -7,6 +8,7 @@ from pathlib import Path
 
 import typer
 
+from typesafe_cli.agent_files import upsert_global_agent_files
 from typesafe_cli.detect import detect_agent_info, resolve_agent
 from typesafe_cli.io import emit_success, fail
 
@@ -25,16 +27,19 @@ SKILL_DIR_BY_AGENT = {
     "generic-agent": ".agents/skills",
 }
 
-USER_SKILL_DIR_BY_AGENT = {
-    "claude-code": Path.home() / ".claude" / "skills",
-    "cursor": Path.home() / ".cursor" / "skills",
-    "windsurf": Path.home() / ".windsurf" / "skills",
-    "gemini-code": Path.home() / ".gemini" / "skills",
-    "codex": Path.home() / ".agents" / "skills",
-    "opencode": Path.home() / ".agents" / "skills",
-    "grok": Path.home() / ".agents" / "skills",
-    "generic-agent": Path.home() / ".agents" / "skills",
-}
+def _user_skill_dir(agent: str, *, home: Path | None = None) -> Path:
+    root = home or Path.home()
+    mapping = {
+        "claude-code": root / ".claude" / "skills",
+        "cursor": root / ".cursor" / "skills",
+        "windsurf": root / ".windsurf" / "skills",
+        "gemini-code": root / ".gemini" / "skills",
+        "codex": root / ".codex" / "skills",
+        "opencode": root / ".agents" / "skills",
+        "grok": root / ".agents" / "skills",
+        "generic-agent": root / ".agents" / "skills",
+    }
+    return mapping.get(agent, root / ".agents" / "skills")
 
 EXISTING_PROJECT_DIRS = (
     ".agents/skills",
@@ -48,7 +53,11 @@ EXISTING_PROJECT_DIRS = (
 def install(
     target: str = typer.Option("auto", "--target", help="claude, cursor, codex, grok, or auto"),
     directory: Path | None = typer.Option(None, "--dir", help="Explicit skills directory"),
-    project: bool = typer.Option(True, "--project/--global", help="Install into the current project (default)"),
+    global_install: bool = typer.Option(
+        False, "--global", "-g", help="Install for this user, all projects (same as npx skills add -g)"
+    ),
+    project: bool = typer.Option(False, "--project", help="Install into the current project only"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Do not ask global vs project"),
     offline: bool = typer.Option(False, "--offline", help="Use the vendored official skill, skip GitHub"),
 ) -> None:
     try:
@@ -59,7 +68,8 @@ def install(
         fail(code="request", message=f"could not load skills: {exc}", exit_code=1)
 
     agent = resolve_agent(target=target)
-    dest_root = directory if directory is not None else _skills_root(agent=agent, project=project)
+    scope = _resolve_scope(global_install=global_install, project=project, yes=yes)
+    dest_root = directory if directory is not None else _skills_root(agent=agent, project=scope == "project")
     written: list[str] = []
     try:
         pairs = [
@@ -71,15 +81,19 @@ def install(
             path.parent.mkdir(parents=True, exist_ok=True)
             path.write_text(body, encoding="utf-8")
             written.append(str(path))
+        if scope == "global" and directory is None:
+            for path in upsert_global_agent_files(home=Path.home(), agent=agent):
+                written.append(str(path))
     except OSError as exc:
         fail(code="request", message=str(exc), exit_code=1)
 
     emit_success(
         data={
             "agent": agent,
+            "scope": scope,
             "written": written,
             "source": "offline-vendored" if offline else "github-or-vendored",
-            "note": "Installed typesafe-ai (design) and typesafe-cli (collect state, then typesafe ask). Agents cannot access TYPESAFE_* env vars.",
+            "note": "Installed typesafe-ai (design) and typesafe-cli (collect state, then typesafe ask). Global installs also write a TypeSafe pointer into the user agent file (CLAUDE.md / AGENTS.md / ~/.grok/rules). Agents cannot access TYPESAFE_* env vars.",
         },
         command="skills install",
     )
@@ -135,4 +149,18 @@ def _skills_root(*, agent: str, project: bool) -> Path:
                 return candidate
         rel = SKILL_DIR_BY_AGENT.get(agent, ".agents/skills")
         return cwd / rel
-    return USER_SKILL_DIR_BY_AGENT.get(agent, Path.home() / ".agents" / "skills")
+    return _user_skill_dir(agent)
+
+
+def _resolve_scope(*, global_install: bool, project: bool, yes: bool) -> str:
+    if global_install and project:
+        fail(code="usage", message="use only one of --global or --project", exit_code=2)
+    if global_install:
+        return "global"
+    if project:
+        return "project"
+    if yes or not sys.stdin.isatty():
+        return "project"
+    if typer.confirm("Install globally for all projects on this machine?", default=False):
+        return "global"
+    return "project"

{typesafeai_cli-0.3.2 → typesafeai_cli-0.3.3}/src/typesafe_cli/data/typesafe-ai/CLI.md

@@ -1,6 +1,6 @@
 # Using the typesafe CLI
 
-Live evaluations: follow the **typesafe-cli** skill. Prefer `find`, `rank`, `extract`, `verify`, `screen`, `suggest-skill`, and `decide` when those flags fit; otherwise collect local state, write JSON under `${TMPDIR:-/tmp}/codex/<project>/`, then `typesafe ask`. Never drop those files in the git tree. This sidecar does not replace that skill or the official TypeSafe skill.
+Live evaluations: follow the **typesafe-cli** skill. Prefer `find`, `rank`, `extract`, `verify`, `screen`, `suggest-skill`, and `decide` when those flags fit; otherwise collect local state, write JSON under `${TMPDIR:-/tmp}/codex/<project>/`, then `typesafe ask`. Invalid answers fail closed. Never drop those files in the git tree. This sidecar does not replace that skill or the official TypeSafe skill.
 
 ## Secrets