@inneranimalmedia/agentsam-sdk 2.4.1 → 2.6.0

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.

package/skills/agentsam-app-fundamentals/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: agentsam-app-fundamentals
+description: >
+  Keep application-building work grounded in execution domains, contracts, credentials,
+  dependency graphs, AST evidence, Merkle evidence, and explicit I/O boundaries. Use when
+  adding or reviewing a feature, service, package, API, auth flow, secret, integration,
+  frontend/backend boundary, worker, webhook, or external credentialed destination. Also
+  use for quick reminders when a large codebase makes the underlying mechanics hard to
+  keep in working memory. Triggers on "app fundamentals", "quick bytes", "trust boundary",
+  "client secret", "redirect URI", "frontend/backend", "AST", "Merkle", "contract drift",
+  "service boundary", "credentialed destination", and "where should this logic live".
+metadata:
+  short-description: "Application-building laws: ownership, contracts, credentials, graphs, AST, and Merkle evidence"
+  aliases:
+    - app-fundamentals
+    - application-fundamentals
+    - quick-bytes
+user-invocable: true
+---
+
+# AgentSam Application Fundamentals
+
+Use this skill as a **small engineering compass**, not a giant textbook. A large
+platform becomes manageable when every feature can answer a few mechanical
+questions: who executes it, who owns authority, what contract crosses the boundary,
+what credential is used, what it depends on, and what evidence proves the change.
+
+## Quick bytes
+
+- **Execution domain:** trust follows who controls the machine/runtime, not the folder name.
+- **Browser/client:** user-controlled and therefore observable/tamperable. Never make it the final authority for security or privileged state changes.
+- **Server/backend:** operator-controlled execution. Re-verify identity, authorization, ownership, prices, permissions, and other invariants here.
+- **Import:** a dependency edge. **Export:** a public contract another module may depend on.
+- **AST:** parsed code structure. Use it to identify symbols, imports/exports, calls, environment access, and execution-domain contradictions without relying on text grep alone.
+- **Dependency graph/DAG:** the map of what depends on what. It determines blast radius, build order, affected tests, and what can run in parallel.
+- **Schema/contract:** the agreed shape at a boundary. Compile-time types help; runtime validation proves real external data matches the contract.
+- **Merkle/content hash:** identity for observed bytes. A changed root proves something changed; an unchanged root proves the captured content is identical under the same policy.
+- **Semantic metadata root:** identity for the indexed/classified view of those bytes. It can change when execution classification or parser-derived meaning changes even when content does not.
+- **Client ID:** usually a public application identifier. **Client secret/API secret:** a credential proving authority; keep it out of browser code and public bundles.
+- **Redirect URI:** an explicitly registered destination for an authorization flow. The provider returns to the callback; your backend verifies the flow, establishes your app session, then chooses the final in-app destination.
+- **Firewall/WAF:** an ingress filter. It reduces hostile traffic; it does not replace authentication, authorization, ownership checks, runtime validation, or least privilege.
+- **Hook:** code that runs automatically because a lifecycle event occurred. Treat hooks as explicit I/O contracts, not mystery scripts.
+
+If one of those concepts is fuzzy for the current task, read the matching reference
+before editing.
+
+## The six questions for every feature
+
+Before changing code, be able to answer:
+
+1. **User behavior:** what can the user now do?
+2. **Execution owner:** which runtime is trusted to make the decision or perform the side effect?
+3. **Contract:** what request/event/type/schema crosses each boundary?
+4. **State:** what is ephemeral, browser-local, durable, cached, or externally owned?
+5. **Credentialed destinations:** which external systems are called, from which runtime, with which public IDs/secrets/scopes?
+6. **Proof:** which tests, AST/index evidence, Merkle receipt, runtime response, or observable metric proves it works?
+
+If a feature cannot answer these, it is not ready to be called complete.
+
+## Build vertical slices, not disconnected layers
+
+For application work, trace the real behavior end to end:
+
+```text
+user action
+  -> client intent
+  -> validated boundary contract
+  -> trusted server/domain operation
+  -> database/service/provider side effect
+  -> response/event
+  -> client state/render
+  -> test + runtime proof
+```
+
+A button without the trusted operation behind it is incomplete. A backend endpoint
+without a real consumer may be dead surface area. A shared type without runtime
+validation is not proof that an external system obeyed the type.
+
+## Credentialed-destination card
+
+Whenever a feature talks to Google, GitHub, Cloudflare, Stripe, a model provider,
+a database, another Worker/service, or any other privileged destination, write down
+this card before wiring it:
+
+```text
+Destination
+  provider/service:
+  purpose:
+  caller execution domain:
+  public identifier(s):
+  secret credential(s):
+  credential owner/runtime:
+  allowed origin/host:
+  callback/redirect/webhook URI(s):
+  scopes/permissions:
+  request contract:
+  response contract:
+  timeout/retry/idempotency:
+  failure behavior:
+  audit/observability:
+  rotation/revocation path:
+```
+
+This turns "a pile of env vars" into an explicit relationship. Environment variable
+names are configuration labels; the credential value is the sensitive authority.
+Validate required configuration at boot or boundary entry and fail clearly.
+
+Read `references/trust-credentials-and-destinations.md` for auth/OAuth and destination
+mechanics.
+
+## Graph law for packages/services/apps
+
+As a system grows, do not rely on remembering which file "goes with" another file.
+Make coupling machine-visible:
+
+```text
+package/service A
+  imports / calls / subscribes to
+package/service B
+  implements contract C
+  owns state D
+  uses credential E
+```
+
+Prefer a single contract authority for cross-surface behavior: a shared type/schema,
+OpenAPI/GraphQL/Protobuf definition, event schema, or other versioned interface. Use
+AST/import graphs and package metadata to determine affected dependents instead of
+manually searching a million-line repository.
+
+Read `references/graphs-contracts-ast-merkle.md` for the deeper model.
+
+## AgentSam evidence tools
+
+Prefer deterministic evidence before broad model reasoning:
+
+```bash
+agentsam inspect --json
+agentsam inspect --execution-domain browser --view files --json
+agentsam security scan --path .
+agentsam merkle ...
+agentsam index ...
+agentsam search ...
+```
+
+Use repository/index tools to narrow the relevant graph. Do not dump the whole repo
+or all tool schemas into context.
+
+## Rules while building
+
+1. Never infer trust from `frontend/`, `backend/`, `worker/`, or `shared/` names alone; verify execution reality.
+2. Never put a long-lived secret into code delivered to a user-controlled runtime.
+3. Never let client-side validation be the only security or correctness check.
+4. Never introduce a second contract authority when an existing canonical schema/type can be extended.
+5. Never change a shared contract without identifying downstream dependents.
+6. Never treat a Merkle hash as proof of correctness; it proves observed identity/change, not behavior.
+7. Never treat AST/index output as infallible; account for parser coverage, generated/framework code, and explicit classification overrides.
+8. Never let a hook silently mutate unrelated state. Bound its inputs, outputs, permissions, timeout, and failure policy.
+9. Never call a credential "just an env var." Record who owns it, where it may exist, and what it authorizes.
+10. Never ship a cross-layer feature from screenshots alone. Exercise the real I/O path.
+
+## Handoff to progression guard
+
+Once the feature's boundaries are coherent, use `agentsam-progression-guard` to decide
+**when and where those invariants must be re-proven** during commit, CI, deploy, and
+runtime promotion.

package/skills/agentsam-app-fundamentals/references/graphs-contracts-ast-merkle.md

@@ -0,0 +1,89 @@
+# Graphs, Contracts, AST, and Merkle Evidence
+
+## The codebase is a graph
+
+A large application is easier to reason about when you stop treating it as a folder
+maze and start treating it as a graph:
+
+```text
+files -> symbols -> imports/calls -> packages -> services -> external destinations
+```
+
+The graph answers questions humans should not have to remember:
+
+- If package C changes, which apps depend on it?
+- Which browser entrypoints can reach this server-only module?
+- Which route consumes this schema?
+- Which service owns a database write?
+- Which packages can build/test in parallel?
+- Which consumers must be revalidated after a contract change?
+
+A DAG is especially useful for build/test ordering when cycles are absent or have been
+made explicit.
+
+## AST is structure, not text coincidence
+
+An Abstract Syntax Tree is the parsed structural representation of source code. It can
+reliably distinguish function declarations, imports, calls, environment accesses,
+and other syntax that a plain text search can only approximate.
+
+AgentSam should use AST evidence to derive dependency and execution-boundary facts,
+then preserve parser coverage/errors so an agent knows where certainty ends.
+
+Useful AST-derived facts include:
+
+- imports/exports and resolved local edges;
+- symbol declarations and references;
+- server/runtime-only dependency use;
+- environment variable access names (never secret values);
+- browser-reachable versus server-owned code;
+- contract/schema ownership hints.
+
+## Contracts make coupling explicit
+
+For a frontend/backend or service/service boundary, prefer one canonical contract
+source. Depending on the system that can be a TypeScript package, runtime schema,
+OpenAPI document, GraphQL schema, Protobuf definition, event schema, or equivalent.
+
+Compile-time types catch code drift before build. Runtime validation catches real data
+that violates the contract after types have been erased or when the caller is outside
+the type system. Contract tests can prove independent producer/consumer systems still
+agree.
+
+## Merkle is the evidence identity layer
+
+Merkle hashing gives a deterministic identity to a captured file tree. If one included
+file changes, the root changes. This makes before/after receipts cheap to compare and
+lets CI/deploy systems cache or target work by content identity.
+
+AgentSam separates two identities:
+
+```text
+content root
+  observed included bytes/paths
+
+semantic metadata root
+  classified/indexed meaning derived from those bytes
+```
+
+The semantic root can change after a classifier/parser upgrade or execution-domain
+classification change even when source bytes remain identical. That distinction is
+important: source identity and interpretation identity answer different questions.
+
+## The repair proof loop
+
+For structural repairs, prefer:
+
+```text
+snapshot A
+  -> contradiction finding + evidence refs
+  -> isolated bounded repair
+  -> build/type/test/security checks
+  -> snapshot B
+  -> prove target contradiction disappeared
+  -> prove no disallowed new contradictions
+  -> emit receipt
+```
+
+The model may propose the repair, but deterministic evidence should decide whether the
+repair actually satisfied the invariant.