@inneranimalmedia/agentsam-sdk 2.4.0 → 2.5.0

package/protocol/context/resolved-context-pack.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/context/resolved-context-pack.schema.json",
+  "title": "ResolvedContextPack",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["objective", "refs", "items", "budget", "receipt"],
+  "properties": {
+    "objective": { "type": "string", "minLength": 1 },
+    "refs": { "type": "array", "items": { "type": "string" } },
+    "rules": { "type": ["object", "null"] },
+    "items": {
+      "type": "array",
+      "items": { "$ref": "./context-item.schema.json" }
+    },
+    "budget": { "$ref": "./context-budget.schema.json" },
+    "receipt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "chars",
+        "evidence_chars",
+        "system_chars",
+        "estimated_tokens",
+        "sources_considered",
+        "sources_included",
+        "sources_deferred",
+        "deferred_refs"
+      ],
+      "properties": {
+        "chars": { "type": "integer", "minimum": 0 },
+        "evidence_chars": { "type": "integer", "minimum": 0 },
+        "system_chars": { "type": "integer", "minimum": 0 },
+        "estimated_tokens": { "type": "integer", "minimum": 0 },
+        "sources_considered": { "type": "integer", "minimum": 0 },
+        "sources_included": { "type": "integer", "minimum": 0 },
+        "sources_deferred": { "type": "integer", "minimum": 0 },
+        "deferred_refs": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/protocol/context/result-policy.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/context/result-policy.schema.json",
+  "title": "ResultPolicy",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["max_items", "max_chars", "detail"],
+  "properties": {
+    "max_items": { "type": "integer", "minimum": 1, "default": 8 },
+    "max_chars": { "type": "integer", "minimum": 1, "default": 24000 },
+    "detail": {
+      "type": "string",
+      "enum": ["metadata", "card", "excerpt", "range", "full"],
+      "default": "excerpt"
+    }
+  }
+}

package/protocol/knowledge/context-pack.schema.json

@@ -32,6 +32,39 @@
     },
     "diagnostics": {
       "type": "object"
+    },
+    "receipt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "chars",
+        "estimated_tokens",
+        "sources_considered",
+        "sources_included",
+        "sources_deferred"
+      ],
+      "properties": {
+        "chars": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "estimated_tokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "sources_considered": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "sources_included": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "sources_deferred": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
     }
   }
 }

package/protocol/knowledge/retrieval-query.schema.json

@@ -4,19 +4,74 @@
   "type": "object",
   "additionalProperties": false,
   "title": "RetrievalQuery",
-  "required": ["text"],
+  "required": [
+    "text"
+  ],
   "properties": {
-    "text": { "type": "string", "minLength": 1 },
-    "workspace_id": { "type": "string", "minLength": 1, "deprecated": true, "description": "Legacy compatibility metadata only; repository selection is explicit through repository identity." },
-    "repositories": { "type": "array", "items": { "type": "string" } },
-    "product_ids": { "type": "array", "items": { "type": "string" } },
-    "refs": { "type": "array", "items": { "type": "string" } },
-    "intent": { "type": "string", "default": "auto" },
-    "lanes": { "type": "array", "items": { "type": "string" } },
-    "top_k": { "type": "integer", "minimum": 1, "maximum": 100, "default": 12 },
-    "token_budget": { "type": "integer", "minimum": 256, "default": 8000 },
-    "require_current_ref": { "type": "boolean", "default": true },
-    "include_archived": { "type": "boolean", "default": false },
-    "explain": { "type": "boolean", "default": true }
+    "text": {
+      "type": "string",
+      "minLength": 1
+    },
+    "workspace_id": {
+      "type": "string",
+      "minLength": 1,
+      "deprecated": true,
+      "description": "Legacy compatibility metadata only; repository selection is explicit through repository identity."
+    },
+    "repositories": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "product_ids": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "refs": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "intent": {
+      "type": "string",
+      "default": "auto"
+    },
+    "lanes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "top_k": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 8,
+      "default": 8
+    },
+    "token_budget": {
+      "type": "integer",
+      "minimum": 256,
+      "default": 6000,
+      "maximum": 6000
+    },
+    "require_current_ref": {
+      "type": "boolean",
+      "default": true
+    },
+    "include_archived": {
+      "type": "boolean",
+      "default": false
+    },
+    "explain": {
+      "type": "boolean",
+      "default": true
+    },
+    "result_policy": {
+      "$ref": "../context/result-policy.schema.json"
+    }
   }
 }

package/python/README.md

@@ -1,8 +1,8 @@
 # agentsam_sdk (Python) — npm mirror
 
 Core repository/data commands remain **stdlib-only** (`dependencies = []`).
-The Rich terminal UI is an optional `tui` extra and lives with the SDK CLI,
-not in the application tool catalog.
+Rich is an optional renderer dependency used by the SDK's internal terminal preview lab;
+it is not exposed as an installed-user renderer command.
 
 ```bash
 cd python && pip install -e .
@@ -20,14 +20,22 @@ Protocol: [`../protocol/README.md`](../protocol/README.md). Do not advance this
 | `agentsam-site-scrape` | [`../packages/agentsam-site-scrape/`](../packages/agentsam-site-scrape/) | Optional/network (`requests`); crawl→R2. Dual-homed with IAM `tools/agentsam-site-scrape/`. Does **not** fold into `agentsam_sdk`. |
 
 
-## Optional terminal UI
+## Internal Rich renderer preview
+
+The npm SDK owns the public interactive experience. For renderer development only:
+
+```bash
+cd ..
+npm run ui:preview -- tour
+npm run ui:preview -- thinking
+```
+
+The Python module can also be invoked directly after installing the optional extra:
 
 ```bash
 cd python
 pip install -e '.[tui]'
-agentsam tui
-agentsam tui --scene dashboard
-agentsam tui --check
+PYTHONPATH=. python -m agentsam_sdk.tui --scene dashboard --check
 ```
 
-`agentsam_sdk.tui` is presentation-only. It does not define tools or execution policy.
+`agentsam_sdk.tui` is presentation-only. It does not define tools, execution policy, or public CLI vocabulary.

package/python/agentsam_sdk/cli.py

@@ -153,31 +153,10 @@ def _cmd_repository_inspect(args: argparse.Namespace) -> int:
     return repo_inspect.main_cli(argv)
 
 
-def _cmd_tui(args: argparse.Namespace) -> int:
-    from agentsam_sdk.tui.demo import main as tui_main
-
-    argv = ["--scene", args.scene, "--ticks", str(args.ticks)]
-    if args.check:
-        argv.append("--check")
-    if args.force_color:
-        argv.append("--force-color")
-    return tui_main(argv)
-
-
 def build_parser() -> argparse.ArgumentParser:
     ap = argparse.ArgumentParser(prog="agentsam", description="agentsam_sdk CLI")
     sub = ap.add_subparsers(dest="group", required=True)
 
-    tui = sub.add_parser("tui", help="optional Rich terminal UI / live CLI renderables")
-    tui.add_argument(
-        "--scene",
-        choices=("all", "card", "progress", "dashboard", "events", "sprite", "logs", "ship"),
-        default="all",
-    )
-    tui.add_argument("--ticks", type=int, default=48)
-    tui.add_argument("--check", action="store_true", help="render quickly for smoke/CI")
-    tui.add_argument("--force-color", action="store_true")
-    tui.set_defaults(func=_cmd_tui)
 
     data = sub.add_parser("data", help="D1 data audits")
     data_sub = data.add_subparsers(dest="cmd", required=True)

package/python/agentsam_sdk/tui/README.md

@@ -1,22 +1,27 @@
-# Agent Sam TUI
+# Agent Sam Rich renderer lab
 
-Optional terminal presentation for the Python `agentsam` CLI.
+Internal high-fidelity terminal presentation experiments for Agent Sam. This package is a renderer/design surface, not a public user command, tool registry, execution adapter, workflow, or permission boundary.
 
-**Ownership:** UI only. This package is not an Agent Sam tool, tool registry,
-execution adapter, workflow, or permission boundary. It renders state produced
-by real SDK commands.
+The installed npm CLI owns the product lifecycle. Users type `agentsam`; they do not select ANSI versus Rich.
 
-Migrated from `inneranimalmedia/tools_py/agentsam_tui` so the product repo no
-longer presents a TUI prototype as a reusable runtime tool.
+From the SDK repository, preview scenes with:
+
+```bash
+npm run ui:preview -- tour
+npm run ui:preview -- boot
+npm run ui:preview -- setup
+npm run ui:preview -- thinking
+npm run ui:preview -- ready
+```
+
+The Node script selects the renderer internally. For direct Python renderer work:
 
 ```bash
 cd python
 pip install -e '.[tui]'
-agentsam tui
-agentsam tui --scene dashboard
-agentsam tui --check
+PYTHONPATH=. python -m agentsam_sdk.tui --scene dashboard --check
 ```
 
-The core Python SDK remains stdlib-only; `rich` is an optional extra.
+The core Python SDK remains stdlib-only; `rich` is an optional extra. The intended product progression is small: **brand/boot → detect project context → first-run keyboard choices when needed → quiet ready prompt**.
 
-For a zero-dependency Node/ANSI rendering reference, see `../../../../examples/agentsam-tui-ansi.mjs`.
+For the zero-dependency Node/ANSI animation lab, see `../../../../scripts/internal/ansi-ui-preview.mjs`.

package/python/agentsam_sdk/tui/bootstrap.py

@@ -2,9 +2,9 @@
 from __future__ import annotations
 
 _MISSING = (
-    "Python package 'rich' is required for the Agent Sam TUI.\n"
+    "Python package 'rich' is required for the internal Agent Sam Rich preview.\n"
     "  pip install -e './python[tui]'\n"
-    "  agentsam tui\n"
+    "  python -m agentsam_sdk.tui --scene boot\n"
 )
 
 

package/python/agentsam_sdk/tui/demo.py

@@ -1,11 +1,15 @@
-"""Agent Sam Rich TUI demos — six reusable terminal patterns.
+"""Internal Agent Sam Rich render previews.
 
-Run from repo root:
+Run from repo root through the SDK design lane:
+
+    npm run ui:preview -- tour
+    npm run ui:preview -- boot
+    npm run ui:preview -- thinking
+
+Or invoke the renderer module directly after installing the optional Rich extra:
 
     pip install -e './python[tui]'
-    agentsam tui
-    agentsam tui --scene dashboard
-    agentsam tui --check
+    PYTHONPATH=python python -m agentsam_sdk.tui --scene dashboard --check
 """
 
 from __future__ import annotations
@@ -33,6 +37,7 @@ from rich.text import Text
 
 from .frames import COMET, THINK, WALKER
 from .theme import CYAN
+from .onboarding import preview_boot, preview_ready, preview_setup, preview_thinking, preview_tour
 from .widgets import (
     IndexDashboard,
     IndexState,
@@ -45,7 +50,8 @@ from .widgets import (
     tty_hint,
 )
 
-SCENES = ("card", "progress", "dashboard", "events", "sprite", "logs", "ship")
+SCENES = ("boot", "setup", "ready", "thinking", "card", "progress", "dashboard", "events", "sprite", "logs", "ship")
+PREVIEW_SCENES = ("tour", *SCENES)
 
 
 def _sleep(seconds: float, *, fast: bool) -> None:
@@ -182,7 +188,7 @@ def demo_ship_lane(console, *, ticks: int = 24, fast: bool = False) -> None:
     steps = [
         ("validate", "python tests"),
         ("package", "agentsam-sdk"),
-        ("cli", "agentsam tui"),
+        ("cli", "internal UI preview"),
         ("run", "operator action"),
         ("receipt", "status captured"),
         ("done", "command complete"),
@@ -219,6 +225,10 @@ def demo_ship_lane(console, *, ticks: int = 24, fast: bool = False) -> None:
 
 
 SCENE_FNS = {
+    "boot": preview_boot,
+    "setup": preview_setup,
+    "ready": preview_ready,
+    "thinking": preview_thinking,
     "card": demo_status_card,
     "progress": demo_progress,
     "dashboard": demo_live_dashboard,
@@ -230,11 +240,16 @@ SCENE_FNS = {
 
 
 def run_scene(name: str, console, *, ticks: int, fast: bool) -> None:
+    if name == "tour":
+        console.print()
+        console.print(Rule("[bold iam.cyan]guided CLI tour[/]"))
+        preview_tour(console, fast=fast, ticks=ticks)
+        return
     fn = SCENE_FNS[name]
     console.print()
     console.print(Rule(f"[bold iam.cyan]{name}[/]"))
     kwargs = {"fast": fast}
-    if name in {"progress", "dashboard", "sprite", "ship"}:
+    if name in {"boot", "setup", "ready", "thinking", "progress", "dashboard", "sprite", "ship"}:
         kwargs["ticks"] = ticks
     fn(console, **kwargs)
 
@@ -246,7 +261,7 @@ def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
     )
     parser.add_argument(
         "--scene",
-        choices=("all", *SCENES),
+        choices=("all", *PREVIEW_SCENES),
         default="all",
         help="Which demo to run (default: all)",
     )
@@ -283,7 +298,7 @@ def main(argv: list[str] | None = None) -> int:
         run_scene(name, console, ticks=ticks, fast=fast)
 
     console.print()
-    console.print("[bold iam.green]Done.[/]  Next: wire these renderables into real SDK CLI commands.")
+    console.print("[bold iam.green]Preview complete.[/]  Internal renderer lab; bare `agentsam` owns the product boot flow.")
     return 0
 
 

package/python/agentsam_sdk/tui/onboarding.py

@@ -0,0 +1,208 @@
+"""Preview-only startup and onboarding compositions for the Agent Sam CLI.
+
+These scenes intentionally do not perform setup or mutate local state. They let us
+judge the terminal UX before wiring the same presentation primitives into
+`agentsam`, `agentsam init`, and `agentsam shell`.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+from .bootstrap import require_rich
+
+require_rich()
+
+from rich.align import Align
+from rich.console import Group
+from rich.live import Live
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from .frames import BRAILLE, MOON, THINK
+
+
+@dataclass(frozen=True)
+class PreviewContext:
+    project: str = "agentsam-sdk"
+    cwd: str = "~/agentsam-sdk"
+    shell: str = "zsh"
+    platform: str = "macOS"
+    version: str = "2.5.0"
+
+
+def _sleep(seconds: float, *, fast: bool) -> None:
+    time.sleep(0.0 if fast else seconds)
+
+
+def _brand_header(ctx: PreviewContext, *, tick: int = 0) -> Group:
+    pulse = MOON[tick % len(MOON)]
+    title = Text()
+    title.append("  Agent Sam", style="bold iam.heading")
+    title.append(f"  {pulse}", style="bold iam.cyan")
+    meta = Text(
+        f"  SDK {ctx.version}  ·  {ctx.platform}  ·  {ctx.shell}",
+        style="iam.muted",
+    )
+    return Group(title, meta)
+
+
+def _boot_card(ctx: PreviewContext, *, tick: int, phase: int) -> Panel:
+    states = (
+        ("environment", "Detecting terminal", phase >= 1),
+        ("project", ctx.project, phase >= 2),
+        ("shell", f"{ctx.shell} · {ctx.cwd}", phase >= 3),
+        ("runtime", "Local-first", phase >= 4),
+    )
+    rows = Table.grid(padding=(0, 2))
+    rows.add_column(style="iam.muted", justify="right", min_width=12)
+    rows.add_column(min_width=34)
+    for index, (label, value, ready) in enumerate(states):
+        if ready:
+            mark = "[iam.green]✓[/]"
+            body = f"[iam.text]{value}[/]"
+        elif index == phase:
+            mark = f"[bold iam.cyan]{BRAILLE[tick % len(BRAILLE)]}[/]"
+            body = f"[iam.muted]{value}[/]"
+        else:
+            mark = "[dim]·[/]"
+            body = f"[dim]{value}[/]"
+        rows.add_row(label, f"{mark}  {body}")
+    return Panel(
+        Group(_brand_header(ctx, tick=tick), Text(""), rows),
+        border_style="iam.cyan",
+        padding=(1, 2),
+        subtitle="[iam.muted]starting locally — no cloud required[/]",
+        width=62,
+    )
+
+
+def preview_boot(console, *, fast: bool = False, ticks: int = 24) -> None:
+    """Compact cold-start sequence: identity, environment, cwd, then handoff."""
+    ctx = PreviewContext()
+    frames = max(8, min(ticks, 28))
+    with Live(console=console, refresh_per_second=18, transient=False) as live:
+        for i in range(frames):
+            phase = min(4, i // max(1, frames // 5))
+            live.update(_boot_card(ctx, tick=i, phase=phase))
+            _sleep(0.055, fast=fast)
+        live.update(_boot_card(ctx, tick=frames, phase=4))
+    console.print("  [iam.green]✓[/] Ready  [iam.muted]· type [bold]/help[/] when you want the map[/]")
+
+
+def _setup_panel(step: int, tick: int, ctx: PreviewContext) -> Panel:
+    steps = [
+        ("Project", "Use this folder", ctx.cwd),
+        ("Local runtime", "Keep execution on this machine", "recommended"),
+        ("Terminal", "Use your existing shell", ctx.shell),
+        ("Agent", "Enable Agent Sam when you need it", "optional"),
+        ("Done", "Open the guided shell", "agentsam shell"),
+    ]
+    grid = Table.grid(padding=(0, 2))
+    grid.add_column(width=3, justify="center")
+    grid.add_column(min_width=15)
+    grid.add_column(min_width=29)
+    for i, (label, description, answer) in enumerate(steps):
+        if i < step:
+            marker = "[iam.green]✓[/]"
+            label_style = "iam.text"
+            detail = f"[iam.muted]{answer}[/]"
+        elif i == step:
+            marker = f"[bold iam.cyan]{MOON[tick % len(MOON)]}[/]"
+            label_style = "bold iam.heading"
+            detail = f"[iam.cyan]{description}[/]\n[dim]  {answer}[/]"
+        else:
+            marker = "[dim]○[/]"
+            label_style = "dim"
+            detail = f"[dim]{description}[/]"
+        grid.add_row(marker, f"[{label_style}]{label}[/]", detail)
+    footer = "Enter choose  ·  ↑↓ move  ·  Esc back" if step < len(steps) - 1 else "Enter open shell  ·  setup can be changed later"
+    return Panel(
+        grid,
+        title="[bold iam.heading]Set up Agent Sam[/]",
+        subtitle=f"[iam.muted]{footer}[/]",
+        border_style="iam.cyan",
+        padding=(1, 2),
+        width=68,
+    )
+
+
+def preview_setup(console, *, fast: bool = False, ticks: int = 30) -> None:
+    """Progressive-discovery wizard mock: one decision at a time, no wall of text."""
+    ctx = PreviewContext()
+    console.print(_brand_header(ctx))
+    console.print("  [iam.muted]First run · five small choices. Nothing is uploaded.[/]")
+    console.print()
+    steps = 5
+    with Live(console=console, refresh_per_second=12, transient=False) as live:
+        for step in range(steps):
+            loops = 1 if fast else max(2, min(5, ticks // steps))
+            for tick in range(loops):
+                live.update(_setup_panel(step, tick, ctx))
+                _sleep(0.12, fast=fast)
+        live.update(_setup_panel(steps - 1, 4, ctx))
+
+
+def _ready_panel(ctx: PreviewContext, *, tick: int) -> Panel:
+    hint = Table.grid(padding=(0, 2))
+    hint.add_column(style="iam.cyan", min_width=14)
+    hint.add_column(style="iam.muted")
+    hint.add_row("/help", "show the command map")
+    hint.add_row("/status", "check project + local services")
+    hint.add_row("/agent <goal>", "ask Agent Sam to work with you")
+    hint.add_row("regular shell", "git, npm, python, etc. stay normal")
+
+    prompt = Text()
+    prompt.append("sam", style="bold iam.cyan")
+    prompt.append(f"  {ctx.cwd}", style="iam.muted")
+    prompt.append("  › ", style="bold iam.heading")
+    prompt.append("_" if tick % 2 == 0 else " ", style="iam.cyan")
+
+    return Panel(
+        Group(_brand_header(ctx, tick=tick), Text(""), hint, Text(""), prompt),
+        title="[bold iam.heading]Ready[/]",
+        border_style="iam.green",
+        padding=(1, 2),
+        width=68,
+    )
+
+
+def preview_ready(console, *, fast: bool = False, ticks: int = 12) -> None:
+    """The final quiet landing state: useful hints, then get out of the way."""
+    ctx = PreviewContext()
+    loops = 2 if fast else max(4, min(ticks, 16))
+    with Live(console=console, refresh_per_second=4, transient=False) as live:
+        for i in range(loops):
+            live.update(_ready_panel(ctx, tick=i))
+            _sleep(0.22, fast=fast)
+
+
+def preview_thinking(console, *, fast: bool = False, ticks: int = 18) -> None:
+    """Small assistant activity animation intended for inline use, not a full screen."""
+    loops = 3 if fast else max(6, min(ticks, 24))
+    with Live(console=console, refresh_per_second=14, transient=False) as live:
+        for i in range(loops):
+            frame = THINK[i % len(THINK)]
+            body = Text(frame, style="bold iam.cyan", no_wrap=True)
+            live.update(
+                Panel(
+                    Align.center(body),
+                    title="[bold iam.heading]Agent Sam[/]",
+                    subtitle="[iam.muted]thinking · working locally[/]",
+                    border_style="iam.cyan",
+                    width=34,
+                    padding=(0, 1),
+                )
+            )
+            _sleep(0.09, fast=fast)
+
+
+def preview_tour(console, *, fast: bool = False, ticks: int = 24) -> None:
+    preview_boot(console, fast=fast, ticks=ticks)
+    console.print()
+    preview_setup(console, fast=fast, ticks=ticks)
+    console.print()
+    preview_thinking(console, fast=fast, ticks=ticks)
+    console.print()
+    preview_ready(console, fast=fast, ticks=ticks)

package/python/tests/test_tui_cli.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import contextlib
+import io
 import unittest
 
 from agentsam_sdk.cli import build_parser
@@ -7,13 +9,12 @@ from agentsam_sdk.tui.frames import BRAILLE, COMET, MOON, THINK, WALKER
 
 
 class TuiCliTests(unittest.TestCase):
-    def test_tui_command_is_registered_without_importing_rich(self):
-        args = build_parser().parse_args(["tui", "--scene", "card", "--check"])
-        self.assertEqual(args.group, "tui")
-        self.assertEqual(args.scene, "card")
-        self.assertTrue(args.check)
+    def test_tui_is_not_a_public_python_cli_command(self):
+        with contextlib.redirect_stderr(io.StringIO()):
+            with self.assertRaises(SystemExit):
+                build_parser().parse_args(["tui"])
 
-    def test_animation_frames_are_available_without_rich(self):
+    def test_animation_frames_remain_available_to_internal_renderers(self):
         self.assertGreater(len(BRAILLE), 0)
         self.assertGreater(len(MOON), 0)
         self.assertGreater(len(WALKER), 0)

package/skills/README.md

@@ -0,0 +1,21 @@
+# AgentSam Skills
+
+Portable, on-demand AgentSam behavior modules. Skills keep specialized guidance
+out of the permanent system prompt and load deeper `references/` only when the
+current task calls for them.
+
+## Canonical skills
+
+- `agentsam-jr-dev/` — explain, inspect, build, and revise real software using
+  beginner-friendly language grounded in the actual repository and runtime.
+
+- `agentsam-app-fundamentals/` — quick application-building laws for trust,
+  contracts, credentials, dependency graphs, AST evidence, and Merkle evidence.
+- `agentsam-progression-guard/` — checkpoint/hook discipline for local work, CI,
+  deploy, postdeploy verification, promotion, runtime observation, and rollback.
+
+List or open them with `agentsam skills`; aliases such as `quick-bytes` and
+`no-regress` are intentionally short enough for terminal use.
+
+Apps may contain host-specific skill directories of their own. Those do not
+replace the portable SDK skills in this directory.