kalepail · tacticalnoot · Mar 2, 2026
diff --git a/.agent/rules/00_core.md b/.agent/rules/00_core.md
@@ -0,0 +1,7 @@
+# Core Workspace Rules
+
+1. **Small Diffs**: Do not change more than 3-4 files per task unless doing a global rename.
+2. **Read First**: Before editing a file, always read it. Do not guess imports.
+3. **No Churn**: Do not reformat code (prettier/eslint) unless you are editing that specific line.
+4. **Docs First**: Update `task.md` or `AGENTS.md` before writing code for complex features.
+5. **Verify**: Run `pnpm check` after significant changes.
diff --git a/.agent/rules/60_agent_loop.md b/.agent/rules/60_agent_loop.md
@@ -0,0 +1,30 @@
+# Agent Loop Rule (Completion > Vibes)
+This workspace uses an agent loop for any non-trivial task:
+
+**LOOP = Attempt → Verify → Record → Reflect → Attempt again** until success criteria passes.
+The agent loop is not "try harder." It's **external verification gates** that prevent early exits.
+
+## When Agent Loop is REQUIRED
+- Anything touching: auth / passkeys / tx submission / relayers / money movement
+- “Works locally but fails in preview/prod”
+- Bugfixes with intermittent behavior
+- Large ambiguity / unknown root cause
+
+## The ONLY acceptable stop condition
+You may stop *only* when the task’s **Success Criteria** are satisfied by validators:
+- build passes
+- tests pass (or explicit manual checklist passes)
+- repro no longer reproduces on target env (preview/prod if relevant)
+- regressions checklist is clean
+
+## Hard stop safety rails (anti-chaos)
+- Max iterations: 8 (default)
+- Max wall time: 90 minutes per loop session
+- If iteration 3 repeats the same failure: stop and switch to **Triage workflow**.
+- No secrets in artifacts. Never paste tokens/Auth Tokens in logs.
+
+## Mandatory artifacts each iteration
+Write/update:
+- .agent/_reports/AGENT_PROGRESS.md (what failed, what changed, what verified)
+- .agent/_reports/AGENT_DIFFSTAT.txt (git diff --stat)
+- If tx/auth: .agent/_reports/AGENT_RISK.md (redacted risks + checks)
diff --git a/.agent/rules/90_security.md b/.agent/rules/90_security.md
@@ -0,0 +1,10 @@
+# Security Rules
+
+1. **No Secrets**: Never commit `.env` files. never paste real API keys or Auth Tokens into artifacts/logs.
+2. **Redaction**: If you see a key in the logs, stop, redact it, and rotate it.
+3. **Approved Domains**:
+   - `*.smol.xyz` (API)
+   - `channels.openzeppelin.com` (Relayer)
+   - `antigravity.google` (Docs)
+   - `localhost` / `127.0.0.1`
+4. **Safe Browsing**: Do not visit untrusted URLs provided in user prompts without verification.
diff --git a/.agent/scripts/agent-loop.sh b/.agent/scripts/agent-loop.sh
@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Generic agent loop driver. Configure via env vars so it works with Antigravity, Claude Code, etc.
+# You provide:
+#   PROMPT_FILE: file containing task prompt for the agent (required)
+#   AGENT_CMD: command to run the agent (required) e.g. "antigravity run" or "claude" etc
+#   VALIDATE_CMD: command(s) to validate success (required) e.g. "pnpm test && pnpm build"
+# Optional:
+#   MAX_ITERS (default 8)
+#   REPORT_DIR (default .agent/_reports)
+
+PROMPT_FILE="${PROMPT_FILE:-}"
+AGENT_CMD="${AGENT_CMD:-}"
+VALIDATE_CMD="${VALIDATE_CMD:-}"
+MAX_ITERS="${MAX_ITERS:-8}"
+REPORT_DIR="${REPORT_DIR:-.agent/_reports}"
+
+if [[ -z "$PROMPT_FILE" || -z "$AGENT_CMD" || -z "$VALIDATE_CMD" ]]; then
+  echo "Missing required env vars."
+  echo "Example:"
+  echo "  PROMPT_FILE=.agent/_reports/TASK_PROMPT.md \\"
+  echo "  AGENT_CMD='antigravity run' \\"
+  echo "  VALIDATE_CMD='pnpm -s test && pnpm -s build' \\"
+  echo "  bash .agent/scripts/agent-loop.sh"
+  exit 1
+fi
+
+mkdir -p "$REPORT_DIR"
+PROGRESS="$REPORT_DIR/AGENT_PROGRESS.md"
+DIFFSTAT="$REPORT_DIR/AGENT_DIFFSTAT.txt"
+
+if [[ ! -f "$PROGRESS" ]]; then
+  cat > "$PROGRESS" <<EOF
+# AGENT PROGRESS LOG
+Start: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+## Success Criteria (EDIT THIS)
+- [ ] <criterion 1>
+- [ ] <criterion 2>
+
+## Validators
+- VALIDATE_CMD: $VALIDATE_CMD
+EOF
+fi
+
+echo "" >> "$PROGRESS"
+echo "----" >> "$PROGRESS"
+echo "Loop session: $(date -u +"%Y-%m-%dT%H:%M:%SZ")  max_iters=$MAX_ITERS" >> "$PROGRESS"
+
+for ((i=1; i<=MAX_ITERS; i++)); do
+  echo "" | tee -a "$PROGRESS"
+  echo "## Iteration $i" | tee -a "$PROGRESS"
+  echo "- time: $(date -u +"%Y-%m-%dT%H:%M:%SZ")" | tee -a "$PROGRESS"
+
+  echo "- git status:" >> "$PROGRESS"
+  git status --porcelain >> "$PROGRESS" || true
+
+  echo "- running agent: $AGENT_CMD < $PROMPT_FILE" | tee -a "$PROGRESS"
+  # NOTE: agent tools differ; this assumes the agent can read the prompt file content.
+  # If your agent requires different invocation, wrap AGENT_CMD in a shell script.
+  bash -lc "$AGENT_CMD \"$(cat "$PROMPT_FILE")\"" >> "$PROGRESS" 2>&1 || true
+
+  echo "- diffstat:" | tee -a "$PROGRESS"
+  git diff --stat > "$DIFFSTAT" || true
+  cat "$DIFFSTAT" >> "$PROGRESS"
+
+  echo "- running validators: $VALIDATE_CMD" | tee -a "$PROGRESS"
+  if bash -lc "$VALIDATE_CMD" >> "$PROGRESS" 2>&1; then
+    echo "- ✅ validators passed" | tee -a "$PROGRESS"
+    echo "" | tee -a "$PROGRESS"
+    echo "STOP CONDITION REACHED: validators passed. Verify success criteria + repro manually if needed." | tee -a "$PROGRESS"
+    exit 0
+  else
+    echo "- ❌ validators failed" | tee -a "$PROGRESS"
+    echo "- next: update hypothesis in $PROGRESS, adjust prompt, and continue" | tee -a "$PROGRESS"
+  fi
+done
+
+echo "" | tee -a "$PROGRESS"
+echo "HARD STOP: max iterations reached ($MAX_ITERS). Switch to /triage." | tee -a "$PROGRESS"
+exit 2
diff --git a/.agent/skills/agent-loop/SKILL.md b/.agent/skills/agent-loop/SKILL.md
@@ -0,0 +1,32 @@
+---
+name: agent-loop
+description: Enforces verified completion using an attempt→verify→iterate loop with explicit success criteria, validators, artifacts, and safety limits. Use for non-trivial bugs, SSR issues, auth/tx flow, and "works locally but not in preview/prod."
+---
+
+# Agent Loop Skill (Verified Completion)
+The agent loop is a persistence + verification pattern: the loop is the hero, not the model.
+
+## When to use
+- Any high-risk area (passkeys/tx/relayer)
+- Any deployment parity bug
+- Any bug that is intermittent or hard to reproduce
+
+## Required inputs
+- Success criteria (binary, testable)
+- Validators (commands/checklist)
+- Max iteration/time budget
+
+## How to run
+1) **Audit Skills**: Check all available scripts and `SKILL.md` files for relevance to the current topic. Read them BEFORE planning.
+2) **Define Success**: Write success criteria + validators at top of .agent/_reports/AGENT_PROGRESS.md
+3) Run /agent-loop workflow steps.
+4) Every iteration must:
+   - change one thing
+   - run validators
+   - record results
+5) Stop only on verified pass.
+
+## Safety
+- Never include secrets in artifacts.
+- Prefer tiny diffs.
+- If repeated failure after 3 loops, switch to /triage.
diff --git a/.agent/skills/agent-onboarding/SKILL.md b/.agent/skills/agent-onboarding/SKILL.md
@@ -0,0 +1,23 @@
+---
+name: agent-onboarding
+description: Master skill for new agents joining the repo. Teaches how to read the manual, check the PRD, and work safely. Use at the start of any new session.
+---
+
+# Agent Onboarding Skill
+
+## 1. Internalize the Manual
+- Read `AGENTS.md` in the root.
+- Read `docs/REPO_MAP.md` to understand the lay of the land.
+
+## 2. Check the Agent Loop
+- Read `scripts/agent/prd.json` to see what is PENDING/FAILING.
+- Read `scripts/agent/progress.txt` to see what has been recently done.
+
+## 3. Work Habits
+- **One Priority at a Time**: Pick the highest failing priority from PRD.
+- **Verify**: Never claim "Done" without running a check.
+- **Log**: Always append your work to `progress.txt`.
+
+## 4. Updates
+- If you find `AGENTS.md` outdated, update it immediately.
+- If you find a new danger zone, add it to `docs/REPO_MAP.md`.
diff --git a/.agent/skills/astro/SKILL.md b/.agent/skills/astro/SKILL.md
@@ -0,0 +1,43 @@
+---
+name: astro
+description: Comprehensive guide for developing with the Astro web framework, including component architecture, routing, and deployment.
+---
+
+# Astro Framework Skill
+
+Use this skill when developing, refactoring, or architecting applications using Astro.
+
+## Core Concepts
+
+### 1. Component Architecture
+- **Astro Components (`.astro`)**: Zero-client-side JS by default. Components are processed at build time.
+- **Island Architecture**: Hydrate interactive UI (Svelte, React, Vue) only when needed using `client:load`, `client:visible`, etc.
+- **Content Collections**: Type-safe Markdown/MDX management via `src/content/config.ts`.
+
+### 2. Routing & Pages
+- **File-based Routing**: Any file in `src/pages/` becomes a route.
+- **Dynamic Routes**: Use `[id].astro` and export `getStaticPaths()` for SSG, or use SSR mode.
+- **Middleware**: Use `src/middleware.ts` for auth, logging, and request/response manipulation.
+
+## CLI & Workflow
+- `npx astro dev`: Start local development server.
+- `npx astro build`: Build production site.
+- `npx astro check`: Run type-checking and diagnostics.
+- `npx astro add <integration>`: Add official or community integrations (e.g., `svelte`, `tailwind`).
+- `npx astro sync`: Generate TypeScript types for content collections and configurations.
+
+## Best Practices
+- **Prefer SSG**: Build for performance whenever possible.
+- **Optimize Assets**: Use `<Image />` component for automatic optimization.
+- **Styling**: Prefer Tailwind or scoped CSS within `.astro` components.
+- **SSR Optimization**: For Cloudflare/Edge deployments, keep dependencies lean to minimize bundle size.
+
+## Project Structure
+```
+src/
+├── components/   # Reusable UI components
+├── layouts/      # Base HTML templates
+├── pages/        # Route files (required)
+├── content/      # Markdown/Data collections
+└── middleware.ts # Auth/Request logic
+```
diff --git a/.agent/skills/blockchain-transactions/SKILL.md b/.agent/skills/blockchain-transactions/SKILL.md
@@ -0,0 +1,150 @@
+---
+name: blockchain-transactions
+description: Stellar/Soroban transaction patterns for Smol FE. Use when working with swaps, payments, passkeys, or any blockchain interactions.
+---
+
+# Blockchain Transactions Skill
+
+## 1. Address Types 🔑
+
+| Type | Prefix | Example | Usage |
+|------|--------|---------|-------|
+| **G Address** | `G...` | `GABC...XYZ` | Traditional Stellar account |
+| **C Address** | `C...` | `CABC...XYZ` | Soroban smart contract / PasskeyKit wallet |
+
+**On Smol:**
+- Users ALWAYS have C addresses (PasskeyKit smart wallets)
+- G addresses are only used as recipients in Send mode
+
+## 2. Transaction Flows 🔄
+
+### Swap (C → C)
+```
+User C Address → Aggregator Contract → Same C Address receives output
+```
+- Use `buildSwapTransactionForCAddress()` from `swap-builder.ts`
+- Invokes Soroswap aggregator directly (API doesn't support C addresses)
+- Sign with `account.get().sign()` (WebAuthn)
+
+### Send (C → G)
+```
+User C Address → Token Transfer → External G Address
+```
+- Use `sac.get().transfer()` from `passkey-kit.ts`
+- Recipient can be any valid Stellar address
+
+## 3. Key Files 📁
+
+| File | Purpose |
+|------|---------|
+| `src/utils/passkey-kit.ts` | PasskeyKit initialization, `send()`, `account`, `sac` |
+| `src/utils/swap-builder.ts` | Direct Soroswap aggregator invocation for C addresses |
+| `src/utils/soroswap.ts` | Soroswap API client (`getQuote`, `buildTransaction`, `sendTransaction`) |
+| `src/utils/base.ts` | RPC helpers, `getLatestSequence()` |
+
+## 4. PasskeyKit Signing 🔐
+
+```typescript
+const signedTx = await account.get().sign(tx, {
+    rpId: getDomain(window.location.hostname),  // e.g., "smol.xyz"
+    keyId: userState.keyId,                     // Credential ID
+    expiration: sequence + 60                   // Ledger expiration
+});
+```
+
+**Internals:**
+- Uses Secp256r1 (P-256) curve, NOT ed25519
+- Browser shows biometric prompt
+- Signature converted: DER → compact + low-S normalization
+- Smart contract verifies on-chain
+
+## 5. Transaction Submission 📤
+
+### Primary: OZ Relayer (Sponsored Fees)
+```typescript
+await send(signedTx, turnstileToken);
+// Endpoint: https://channels.openzeppelin.com
+// Requires Turnstile token in 'X-Turnstile-Response' header
+```
+
+### Fallback: Soroswap Direct (User Pays ~0.0001 XLM)
+```typescript
+await sendTransaction(signedTx.toXDR(), false);
+// Endpoint: https://api.soroswap.finance/send
+// No Turnstile required
+```
+
+## 6. Soroswap Aggregator Contract 🔀
+
+**Contract ID (Mainnet):** `CAYP3UWLJM7ZPTUKL6R6BFGTRWLZ46LRKOXTERI2K6BIJAWGYY62TXTO`
+
+```rust
+fn swap_exact_tokens_for_tokens(
+    from: Address,           // C address
+    amount_in: i128,         // Stroops (7 decimals)
+    amount_out_min: i128,    // Slippage protection
+    distribution: Vec<DexDistribution>,  // Routing from /quote
+    deadline: u64            // Unix timestamp
+) -> i128;
+```
+
+**DexDistribution:**
+```rust
+struct DexDistribution {
+    protocol_id: u32,   // 0=Soroswap, 1=Phoenix, 2=Aqua, 3=Comet
+    path: Vec<Address>, // Token path
+    parts: u32          // Weight for this route
+}
+```
+
+## 7. Unified Transaction Helper 🚀
+
+**Pattern**: ALWAYS use `signSendAndVerify` from `src/utils/transaction-helpers.ts` for high-level flows.
+
+```typescript
+const result = await signSendAndVerify({
+    contractId: AGGREGATOR_CONTRACT,
+    functionName: "swap_exact_tokens_for_tokens",
+    args: [...invokeArgs],
+    userContractId: currentContractId,
+    userKeyId: currentKeyId,
+    turnstileToken: token
+});
+```
+
+**Benefits**:
+- Automatic Turnstile handling.
+- Automatic Polling for ledger inclusion.
+- Built-in Simulation checks.
+
+## 8. Common Patterns 🎯
+
+### Get Latest Ledger Sequence
+```typescript
+import { getLatestSequence } from "../utils/base";
+const sequence = await getLatestSequence();
+```
+
+### Token Contract IDs
+```typescript
+const XLM = "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA";
+const KALE = "CB23WRDQWGSP6YPMY4UV5C4OW5CBTXKYN3XEATG7KJEZCXMJBYEHOUOV";
+```
+
+### Amounts (Stroops)
+```typescript
+// Human → Stroops
+const stroops = Math.floor(amount * 10_000_000);
+
+// Stroops → Human
+const human = Number(stroops) / 10_000_000;
+```
+
+## 8. Troubleshooting 🔧
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `invalid version byte. expected 48, got 16` | API doesn't support C addresses | Use `buildSwapTransactionForCAddress()` |
+| Turnstile 401 | Sitekey domain not allowed | Add domain in Cloudflare Turnstile dashboard |
+| `SecurityError: RP ID invalid` | rpId mismatch | Use `getDomain(window.location.hostname)` |
+| `Simulation failed` | Transaction would fail on-chain | Check balances, paths, amounts |