atris 2.5.2 → 2.5.4

package/atris/experiments/benchmark_validate.py

@@ -0,0 +1,70 @@
+"""Benchmark the validator against fixed good/bad fixtures."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+
+
+ROOT = Path(__file__).resolve().parent
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from validate import validate_experiment
+
+
+FIXTURES_DIR = ROOT / "_fixtures"
+
+CASES = [
+    {
+        "path": FIXTURES_DIR / "valid" / "good-experiment",
+        "expect_ok": True,
+        "must_contain": [],
+    },
+    {
+        "path": FIXTURES_DIR / "invalid" / "BadName",
+        "expect_ok": False,
+        "must_contain": ["invalid folder name", "missing required file measure.py"],
+    },
+    {
+        "path": FIXTURES_DIR / "invalid" / "bloated-context",
+        "expect_ok": False,
+        "must_contain": ["program.md too long"],
+    },
+]
+
+
+def main() -> int:
+    passed = 0
+    failures = []
+
+    for case in CASES:
+        issues = validate_experiment(case["path"])
+        is_ok = not issues
+
+        if case["expect_ok"] != is_ok:
+            failures.append(f"{case['path'].name}: expected ok={case['expect_ok']} got ok={is_ok}")
+            continue
+
+        missing = [needle for needle in case["must_contain"] if not any(needle in issue for issue in issues)]
+        if missing:
+            failures.append(f"{case['path'].name}: missing expected issue(s): {', '.join(missing)}")
+            continue
+
+        passed += 1
+
+    total = len(CASES)
+    score = passed / total if total else 0.0
+    print(f"SCORE {score:.4f} ({passed}/{total})")
+
+    if failures:
+        for failure in failures:
+            print(f"FAIL {failure}")
+        return 1
+
+    print("PASS benchmark_validate")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/atris/experiments/validate.py

@@ -0,0 +1,92 @@
+"""Validate experiments for structure and context hygiene."""
+
+from __future__ import annotations
+
+import argparse
+import re
+from pathlib import Path
+
+
+REQUIRED_FILES = ("program.md", "measure.py", "loop.py", "results.tsv")
+MAX_PROGRAM_CHARS = 1200
+MAX_RESULTS_BYTES = 64_000
+SLUG_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+
+
+def find_experiments(root: Path) -> list[Path]:
+    return sorted(
+        path
+        for path in root.iterdir()
+        if path.is_dir() and not path.name.startswith((".", "_"))
+    )
+
+
+def resolve_experiments(root: Path) -> list[Path]:
+    if not root.exists() or not root.is_dir():
+        return []
+
+    # Allow validating a single pack directly, not just a parent directory.
+    if any((root / filename).exists() for filename in REQUIRED_FILES):
+        return [root]
+
+    return find_experiments(root)
+
+
+def validate_experiment(path: Path) -> list[str]:
+    issues: list[str] = []
+
+    if not SLUG_RE.match(path.name):
+        issues.append(f"{path.name}: invalid folder name, use lowercase-hyphen slug")
+
+    for filename in REQUIRED_FILES:
+        if not (path / filename).exists():
+            issues.append(f"{path.name}: missing required file {filename}")
+
+    program_path = path / "program.md"
+    if program_path.exists():
+        size = len(program_path.read_text(encoding="utf-8"))
+        if size > MAX_PROGRAM_CHARS:
+            issues.append(
+                f"{path.name}: program.md too long ({size} chars > {MAX_PROGRAM_CHARS})"
+            )
+
+    results_path = path / "results.tsv"
+    if results_path.exists():
+        size = results_path.stat().st_size
+        if size > MAX_RESULTS_BYTES:
+            issues.append(
+                f"{path.name}: results.tsv too large ({size} bytes > {MAX_RESULTS_BYTES})"
+            )
+
+    return issues
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Validate experiment packs.")
+    parser.add_argument("root", nargs="?", default=".", help="Directory containing experiment packs")
+    args = parser.parse_args()
+
+    root = Path(args.root).resolve()
+    experiments = resolve_experiments(root)
+    if not experiments:
+        print("FAIL: no experiments found")
+        return 1
+
+    all_issues: list[str] = []
+    for path in experiments:
+        all_issues.extend(validate_experiment(path))
+
+    if all_issues:
+        print("FAIL")
+        for issue in all_issues:
+            print(f"- {issue}")
+        return 1
+
+    print(f"PASS: {len(experiments)} experiment(s) valid")
+    for path in experiments:
+        print(f"- {path.name}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/atris/policies/atris-design.md

@@ -52,12 +52,43 @@ dark backgrounds are easier to make look good. steal from places you like — li
 
 **avoid:** static pages with nothing moving, or the opposite — bouncing everything
 
+**specific anti-patterns:**
+- cursor-following lines or elements
+- meteor/particle effects shooting across screen
+- buttons that follow the cursor (harder to click, not clever)
+- FAQ/content that breaks if you scroll past before the fade-in finishes
+- animations that swap styles endlessly without purpose (rotating shapes, morphing buttons)
+
 **the move:** one well-timed animation beats ten scattered ones. page load with staggered reveals (animation-delay) creates more impact than hover effects on every button.
 
 css transitions: 200-300ms, ease-out. that's it.
 
 ---
 
+## hover states
+
+**avoid:**
+- elements that fade out or disappear on hover
+- nav items that shift position or slide horizontally on hover
+- arrows/icons that move backwards or vertically on hover
+- hiding critical info or functionality behind hover (hover doesn't exist on mobile)
+
+**the move:** hover should make elements feel "lickable" — inviting to click. slightly brighten, scale up (1.02-1.05), or add a subtle glow. the user should feel pulled toward clicking, not confused about what happened.
+
+test every hover on mobile. if something only works on hover, it's broken for half your users.
+
+---
+
+## scroll behavior
+
+**avoid:** scrolljacking — never override native browser scroll with custom scroll logic. it feels like "moving through molasses" and users hate it.
+
+**the move:** let the browser handle scrolling. if you want scroll-triggered effects, use intersection observer to trigger animations as sections enter the viewport — but don't mess with scroll speed or direction.
+
+use the "peeking" technique: let a few pixels of the next section peek above the fold instead of full-screen heroes with "scroll down" arrows. this naturally signals more content below.
+
+---
+
 ## backgrounds
 
 **avoid:** solid white, solid light gray, flat nothing
@@ -82,12 +113,47 @@ vary your choices. alternate themes. try different directions between projects.
 
 ---
 
+## information hierarchy
+
+**avoid:** mixing 4-5 competing text styles on one page. labels, headers, subheaders, badges, and body text all fighting for attention.
+
+**the move:** pick 2-3 levels max. one dominant style, one supporting, one accent. if you add a new style, ask: does this earn its place or is it clutter?
+
+---
+
+## hero section (the H1 test)
+
+your hero must answer four questions in seconds:
+1. **what is it?** — clear product description
+2. **who is it for?** — the target user
+3. **to what end?** — why should they care
+4. **what's the CTA?** — one clear next step
+
+if a stranger can't answer all four in 5 seconds of looking at your hero, rewrite it.
+
+---
+
+## assets
+
+**avoid:**
+- blurry or low-res screenshots
+- "fake dashboard" mockups with Fisher-Price primary colors (red/yellow/green/blue)
+- non-system emojis used as decoration (lazy AI tell)
+
+**the move:** real product screenshots at high resolution. if you don't have a product yet, use a well-designed mockup — but make it sharp and believable.
+
+---
+
 ## before shipping
 
 - can you name the aesthetic in 2-3 words?
 - did you pick a real font, not a default?
 - is there at least one intentional animation?
 - does the background have depth?
+- do hover states feel inviting, not confusing?
+- does scrolling feel native?
+- does the hero pass the H1 test (what/who/why/CTA)?
+- are all screenshots/assets crisp?
 - would a designer immediately clock this as ai-generated?
 
 if the last answer is yes, you're not done.

package/atris/skills/README.md

@@ -27,6 +27,7 @@ cp -r atris/skills/[name] ~/.codex/skills/
 |-------|-------------|--------|
 | atris | Workflow enforcement + plan/do/review | `policies/ANTISLOP.md` |
 | autopilot | PRD-driven autonomous execution | — |
+| autoresearch | Bounded keep/revert experiment loops via `atris/experiments/` | — |
 | backend | Backend architecture anti-patterns | `policies/atris-backend.md` |
 | design | Frontend aesthetics policy | `policies/atris-design.md` |
 | calendar | Google Calendar integration via AtrisOS | — |

package/atris/skills/apps/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: apps
+description: View, manage, and trigger Atris apps. Use when user asks about their apps, app status, runs, data, or wants to trigger an app.
+version: 1.0.0
+tags:
+  - apps
+  - atris
+  - management
+---
+
+# Apps
+
+View and manage your Atris apps — status, runs, data, secrets, members.
+
+## Bootstrap
+
+```bash
+TOKEN=$(node -e "console.log(require('$HOME/.atris/credentials.json').token)" 2>/dev/null \
+  || python3 -c "import json,os; print(json.load(open(os.path.expanduser('~/.atris/credentials.json')))['token'])" 2>/dev/null)
+if [ -z "$TOKEN" ]; then echo "Not logged in. Run: atris login"; exit 1; fi
+echo "Ready."
+```
+
+Base URL: `https://api.atris.ai/api/apps`
+
+Auth: `-H "Authorization: Bearer $TOKEN"`
+
+---
+
+## List My Apps
+
+```bash
+curl -s "https://api.atris.ai/api/apps" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+Returns all apps you own with id, name, slug, description, template, status.
+
+### Filter Apps
+
+```bash
+# Template apps only
+curl -s "https://api.atris.ai/api/apps?filter=template" \
+  -H "Authorization: Bearer $TOKEN"
+
+# Paid apps
+curl -s "https://api.atris.ai/api/apps?filter=paid" \
+  -H "Authorization: Bearer $TOKEN"
+
+# Free apps
+curl -s "https://api.atris.ai/api/apps?filter=free" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+---
+
+## App Details
+
+### Get App Status
+```bash
+curl -s "https://api.atris.ai/api/apps/{slug}/status" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+Returns: last run, next run, health, active members.
+
+### Get App Runs
+```bash
+curl -s "https://api.atris.ai/api/apps/{slug}/runs?limit=10" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### Get Single Run
+```bash
+curl -s "https://api.atris.ai/api/apps/{slug}/runs/{run_id}" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+---
+
+## App Data
+
+### Read All Data
+```bash
+curl -s "https://api.atris.ai/api/apps/{slug}/data" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### Read Specific Collection
+```bash
+curl -s "https://api.atris.ai/api/apps/{slug}/data/{collection}" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### Push Data In
+```bash
+curl -s -X POST "https://api.atris.ai/api/apps/{slug}/ingest" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"collection": "leads", "data": {"name": "Acme", "score": 85}}'
+```
+
+---
+
+## Secrets
+
+### List Secret Keys (names + storage tier)
+```bash
+curl -s "https://api.atris.ai/api/apps/{slug}/secrets" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+Returns key names and where they're stored:
+- `"storage_tier": "cloud"` — encrypted in Atris vault
+- `"storage_tier": "local"` — on your machine at `~/.atris/secrets/{slug}/`
+
+### Store Secret (cloud)
+```bash
+curl -s -X PUT "https://api.atris.ai/api/apps/{slug}/secrets/{key}" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"value": "sk-secret-value"}'
+```
+
+### Register Local Secret (manifest only)
+```bash
+curl -s -X POST "https://api.atris.ai/api/apps/{slug}/secrets/{key}/register-local" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+No value sent. Just tells the web UI "this key exists on my machine."
+
+### Delete Secret
+```bash
+curl -s -X DELETE "https://api.atris.ai/api/apps/{slug}/secrets/{key}" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+---
+
+## Members
+
+### List App Members
+```bash
+curl -s "https://api.atris.ai/api/apps/{slug}/members" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### Add Member (agent operator)
+```bash
+curl -s -X POST "https://api.atris.ai/api/apps/{slug}/members" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"agent_id": "AGENT_ID", "role": "operator"}'
+```
+
+### Remove Member
+```bash
+curl -s -X DELETE "https://api.atris.ai/api/apps/{slug}/members/{agent_id}" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+---
+
+## Trigger
+
+### Run App Now
+```bash
+curl -s -X POST "https://api.atris.ai/api/apps/{slug}/trigger" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"trigger_type": "manual"}'
+```
+
+---
+
+## App Manifest (for published apps)
+
+```bash
+curl -s "https://api.atris.ai/api/apps/{slug}/manifest"
+```
+
+No auth needed. Returns name, description, required secrets, schedule.
+
+### Install a Published App
+
+```bash
+curl -s -X POST "https://api.atris.ai/api/apps/{slug}/install" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+---
+
+## Workflows
+
+### "What apps do I have?"
+1. List apps: `GET /api/apps`
+2. Display: name, slug, template, last run status
+
+### "How is my app doing?"
+1. Get status: `GET /api/apps/{slug}/status`
+2. Get recent runs: `GET /api/apps/{slug}/runs?limit=5`
+3. Show: health, last run time, success/failure, output
+
+### "Check my app's secrets"
+1. List secrets: `GET /api/apps/{slug}/secrets`
+2. Show each key with storage tier (cloud/local)
+3. If required secrets are missing, tell the user how to add them
+
+### "Run my app"
+1. Trigger: `POST /api/apps/{slug}/trigger`
+2. Poll status: `GET /api/apps/{slug}/status` (wait for completion)
+3. Show run result: `GET /api/apps/{slug}/runs?limit=1`
+
+---
+
+## Quick Reference
+
+```bash
+TOKEN=$(node -e "console.log(require('$HOME/.atris/credentials.json').token)")
+
+# List all my apps
+curl -s "https://api.atris.ai/api/apps" -H "Authorization: Bearer $TOKEN"
+
+# App status
+curl -s "https://api.atris.ai/api/apps/SLUG/status" -H "Authorization: Bearer $TOKEN"
+
+# Recent runs
+curl -s "https://api.atris.ai/api/apps/SLUG/runs?limit=5" -H "Authorization: Bearer $TOKEN"
+
+# Trigger a run
+curl -s -X POST "https://api.atris.ai/api/apps/SLUG/trigger" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"trigger_type":"manual"}'
+
+# Read app data
+curl -s "https://api.atris.ai/api/apps/SLUG/data" -H "Authorization: Bearer $TOKEN"
+
+# List secrets (with storage tier)
+curl -s "https://api.atris.ai/api/apps/SLUG/secrets" -H "Authorization: Bearer $TOKEN"
+```

package/atris/skills/autoresearch/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: autoresearch
+description: Karpathy-style keep/revert experiment loop for Atris experiment packs. Use when improving prompts, tools, workers, or bounded repo targets.
+version: 1.0.0
+tags:
+  - experiments
+  - keep-revert
+  - optimization
+  - metrics
+---
+
+# Autoresearch Skill
+
+Autoresearch means one bounded target, one external metric, one keep/revert loop, one append-only log.
+
+## When to use
+
+- prompt optimization
+- worker routing
+- tool behavior
+- evaluation harnesses
+- any repo-local target that can be measured honestly
+
+## Process
+
+1. Read `atris/experiments/<slug>/program.md`
+2. Confirm the target is bounded
+3. Run the baseline with `measure.py`
+4. Apply one candidate change
+5. Rerun the metric
+6. Keep only if the score improves
+7. Write the outcome to `results.tsv`
+8. Revert losses
+
+## Rules
+
+- external metric only
+- no unlogged keeps
+- no broad refactors inside an experiment
+- one experiment pack = one target
+- if variance exists, define the keep margin first
+
+## Commands
+
+```bash
+atris experiments init <slug>
+atris experiments validate
+atris experiments benchmark
+```
+
+## Good output
+
+- short `program.md`
+- honest `measure.py`
+- deterministic `loop.py`
+- append-only `results.tsv`
+
+## Bad output
+
+- "felt better"
+- changed three things at once
+- kept a patch without a measured win
+- no reset/revert path

package/atris/skills/create-app/SKILL.md

@@ -104,6 +104,12 @@ unset secret_val
 echo "Saved locally."
 ```
 
+Register the key in the web UI (manifest only — no value sent):
+```bash
+curl -s -X POST "https://api.atris.ai/api/apps/SLUG/secrets/KEY_NAME/register-local" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
 Verify (key names only, never values):
 ```bash
 ls ~/.atris/secrets/SLUG/

package/atris/skills/design/SKILL.md

@@ -27,10 +27,20 @@ This skill uses the Atris workflow:
 
 **Layout:** break the hero + 3 cards + footer template. asymmetry is interesting. dramatic whitespace.
 
-**Motion:** one well-timed animation beats ten scattered ones. 200-300ms ease-out.
+**Motion:** one well-timed animation beats ten scattered ones. 200-300ms ease-out. no cursor-following lines, no meteor effects, no buttons that chase the cursor.
+
+**Hover:** make elements feel inviting on hover (brighten, subtle scale). never fade out, shift, or hide content behind hover. hover doesn't exist on mobile.
+
+**Scroll:** never override native scroll. use "peeking" (show a few px of next section) instead of full-screen hero + scroll arrow.
+
+**Hero (H1 test):** must answer in 5 seconds — what is it, who is it for, why care, what's the CTA.
+
+**Assets:** high-res screenshots only. no fake dashboards with primary colors. no decorative non-system emojis.
 
 **Backgrounds:** add depth. gradients, patterns, mesh effects. flat = boring.
 
+**Hierarchy:** 2-3 text levels max. don't mix 5 competing styles.
+
 ## Before Shipping Checklist
 
 Run through `atris/policies/atris-design.md` "before shipping" section:
@@ -38,6 +48,10 @@ Run through `atris/policies/atris-design.md` "before shipping" section:
 - distinctive font, not default?
 - at least one intentional animation?
 - background has depth?
+- hover states feel inviting, not confusing?
+- scrolling feels native?
+- hero passes H1 test (what/who/why/CTA)?
+- all assets crisp?
 - would a designer clock this as ai-generated?
 
 ## Atris Commands