Port agent rules from moq and moq.pro, and set up quests

.agents/skills

@@ -0,0 +1 @@
+../.claude/skills

.claude/hooks/direnv.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# Load the project's direnv/nix dev shell into the Claude Code session so Bash
+# tool commands resolve flake-pinned tools (bun, nixfmt, ...) instead of system
+# ones. No-op for anyone without direnv or an .envrc, so non-nix setups are
+# unaffected.
+#
+# Claude Code inlines $CLAUDE_ENV_FILE into the command string of every Bash
+# call, and Linux caps a single argv entry at MAX_ARG_STRLEN, 128KB. This dev
+# shell exports around 190KB, so the environment goes in a sidecar file and
+# $CLAUDE_ENV_FILE gets only a line sourcing it. macOS has no per-argument cap,
+# which is why inlining the whole environment appeared to work there.
+
+set -eu
+
+MARKER='# moq.dev dev shell'
+
+# Nothing to export into without this; older Claude Code versions won't set it.
+[ -n "${CLAUDE_ENV_FILE:-}" ] || exit 0
+
+command -v direnv >/dev/null 2>&1 || exit 0
+
+# Require an explicit project dir so we never approve/export a stray .envrc from
+# some unrelated working directory.
+[ -n "${CLAUDE_PROJECT_DIR:-}" ] || exit 0
+cd "$CLAUDE_PROJECT_DIR" || exit 0
+[ -f .envrc ] || exit 0
+
+# Clear any inherited direnv state so the dev shell is recomputed in full.
+# Without this, a stale DIRENV_DIFF from the parent process makes direnv assume
+# the env is already loaded and emit nothing.
+unset DIRENV_DIR DIRENV_DIFF DIRENV_WATCHES DIRENV_FILE DIRENV_LAYOUT
+
+direnv allow . 2>/dev/null || exit 0
+
+raw=$(mktemp) || exit 1
+scratch=''
+trap 'rm -f "$raw"; [ -z "$scratch" ] || rm -f "$scratch"' EXIT
+
+# Clear inherited variables before restoring the snapshot, including variables
+# that .envrc removed. Otherwise later shells inherit those removed values.
+env -0 >"$raw"
+inherited=()
+while IFS= read -r -d '' entry; do
+    name=${entry%%=*}
+    [[ $name =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] || continue
+    case $name in
+        DIRENV_* | PWD | OLDPWD | SHLVL | _ | SHELLOPTS | BASHOPTS | BASH_VERSINFO | UID | EUID | PPID) continue ;;
+    esac
+    inherited+=("$name")
+done <"$raw"
+
+# Read the environment with `env -0` rather than a shell builtin: nixpkgs builds
+# the non-interactive `bash` without programmable completion, so `compgen` does
+# not exist inside the very dev shell this hook is here to load.
+if ! direnv exec . env -0 >"$raw"; then
+    echo "direnv hook: could not load the dev shell, see the direnv output above." >&2
+    exit 1
+fi
+
+if [ ! -s "$raw" ]; then
+    echo "direnv hook: the dev shell exported nothing, so no tools would resolve." >&2
+    exit 1
+fi
+
+sidecar=$CLAUDE_ENV_FILE.direnv
+# mktemp keeps credentials private and lets readers retain the old snapshot
+# until the replacement has been written successfully.
+scratch=$(mktemp "$sidecar.XXXXXX")
+
+{
+    for name in "${inherited[@]}"; do
+        printf 'unset %s\n' "$name"
+    done
+    while IFS= read -r -d '' entry; do
+        name=${entry%%=*}
+
+        # Skip exported functions (BASH_FUNC_foo%%) and anything else that is not a
+        # plain identifier, since `export` cannot restore those.
+        [[ $name =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] || continue
+
+        # direnv's bookkeeping, and the shell's own state, are not ours to restore.
+        case $name in
+            DIRENV_* | PWD | OLDPWD | SHLVL | _ | SHELLOPTS | BASHOPTS | BASH_VERSINFO | UID | EUID | PPID) continue ;;
+        esac
+
+        printf 'export %s=%q\n' "$name" "${entry#*=}"
+    done <"$raw"
+} >"$scratch"
+
+mv -f "$scratch" "$sidecar"
+
+# Refresh on every SessionStart, but install the sourcing line only once.
+grep -qxF "$MARKER" "$CLAUDE_ENV_FILE" 2>/dev/null && exit 0
+printf '%s\n. %q\n' "$MARKER" "$sidecar" >>"$CLAUDE_ENV_FILE"

.claude/rules/prompting.md

@@ -0,0 +1,9 @@
+---
+paths:
+  - "**/AGENTS.md"
+  - "CONTRIBUTING.md"
+  - "PROMPTING.md"
+  - ".claude/skills/**"
+---
+
+Before editing this file, read `PROMPTING.md` at the repository root and apply it.

.claude/settings.json

@@ -0,0 +1,28 @@
+{
+	"$schema": "https://json.schemastore.org/claude-code-settings.json",
+	"hooks": {
+		"SessionStart": [
+			{
+				"hooks": [
+					{
+						"type": "command",
+						"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/direnv.sh"
+					}
+				]
+			}
+		]
+	},
+	"permissions": {
+		"allow": [
+			"Bash(just *)",
+			"Bash(bun *)",
+			"Bash(bunx *)",
+			"Bash(quest *)",
+			"WebFetch(domain:moq.dev)",
+			"WebFetch(domain:doc.moq.dev)",
+			"WebFetch(domain:docs.astro.build)",
+			"WebFetch(domain:developers.cloudflare.com)"
+		],
+		"ask": ["Bash(just deploy*)", "Bash(bun wrangler deploy*)", "Bash(bunx wrangler deploy*)"]
+	}
+}

.claude/skills/quest-audit/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: quest-audit
+description: Audit outstanding quests for disagreements, conflicts, misaligned priorities, and stale plans, then resolve them with /quest-plan. Use when the user invokes /quest-audit or asks to check the quest tree for consistency.
+---
+
+Run `quest skill audit` and follow its output.
+If `quest` is not installed, follow https://github.com/kixelated/quest/blob/main/SETUP.md first.

.claude/skills/quest-complete/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: quest-complete
+description: Decide which open PRs to merge, then merge them in parallel.
+---
+
+Run `quest skill complete` and follow its output.
+If `quest` is not installed, follow https://github.com/kixelated/quest/blob/main/SETUP.md first.

.claude/skills/quest-delete/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: quest-delete
+description: Abandon a quest.
+---
+
+Run `quest skill delete` and follow its output.
+If `quest` is not installed, follow https://github.com/kixelated/quest/blob/main/SETUP.md first.

.claude/skills/quest-export/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: quest-export
+description: Turn active quests into GitHub issues before leaving Quest. Use when the user invokes /quest-export or asks to export quests before removing Quest.
+---
+
+Run `quest skill export` and follow its output.
+If `quest` is not installed, follow https://github.com/kixelated/quest/blob/main/SETUP.md first.

.claude/skills/quest-import/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: quest-import
+description: Import GitHub issues as quests.
+---
+
+Run `quest skill import` and follow its output.
+If `quest` is not installed, follow https://github.com/kixelated/quest/blob/main/SETUP.md first.

.claude/skills/quest-iterate/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: quest-iterate
+description: Iterate on an open PR to settle its open decisions, fix CI and review findings, and push.
+---
+
+Run `quest skill iterate` and follow its output.
+If `quest` is not installed, follow https://github.com/kixelated/quest/blob/main/SETUP.md first.

.claude/skills/quest-merge/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: quest-merge
+description: Merge a quest once reviews and CI pass.
+---
+
+Run `quest skill merge` and follow its output.
+If `quest` is not installed, follow https://github.com/kixelated/quest/blob/main/SETUP.md first.

.claude/skills/quest-plan/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: quest-plan
+description: Scope and create quests through an interactive interview. Use when the user invokes /quest-plan, asks to plan a quest, or wants unsettled work split into quests.
+---
+
+Run `quest skill plan` and follow its output.
+If `quest` is not installed, follow https://github.com/kixelated/quest/blob/main/SETUP.md first.

.claude/skills/quest-spawn/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: quest-spawn
+description: Start multiple quests in parallel.
+---
+
+Run `quest skill spawn` and follow its output.
+If `quest` is not installed, follow https://github.com/kixelated/quest/blob/main/SETUP.md first.

.claude/skills/quest-start/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: quest-start
+description: Start work on a quest.
+---
+
+Run `quest skill start` and follow its output.
+If `quest` is not installed, follow https://github.com/kixelated/quest/blob/main/SETUP.md first.

.github/workflows/pr.yml

@@ -34,3 +34,5 @@ jobs:
       - uses: cachix/install-nix-action@13d8dd58da0234aa297dedd986986ccb8e7f3e24 # v31
       # Evaluating the shell checks the Nix, package.json, and Docker Bun pins.
       - run: nix eval --raw .#devShells.x86_64-linux.default.drvPath
+      # Just the quest package, not the whole dev shell.
+      - run: nix run .#quest -- check

AGENTS.md

@@ -0,0 +1,164 @@
+# AGENTS.md
+
+## Project Overview
+
+moq.dev is a web blog and demo for Media over QUIC (MoQ) protocol. It's built with Astro, Solid.js, and uses WebTransport to connect to MoQ relay servers for live streaming.
+
+The repo holds three sites, each its own Cloudflare Worker but built and deployed together:
+
+| Site        | Source      | What it is                                            |
+|-------------|-------------|-------------------------------------------------------|
+| `moq.dev`   | `src/`      | The Astro blog and demos                              |
+| `moq.pub`   | `sites/pub` | A bare `<moq-publish-ui>` publisher, no framework     |
+| `moq.watch` | `sites/watch` | A bare `<moq-watch-ui>` player, no framework         |
+
+## Essential Commands
+
+```bash
+# Development
+just dev           # Start the moq.dev dev server with auto-open
+just dev-pub       # moq.pub on :5174
+just dev-watch     # moq.watch on :5173
+
+# Build & Deploy
+just build         # Production build of all three sites
+just deploy        # Deploy all three to Cloudflare (staging by default)
+just deploy live   # Deploy to production
+just prod          # Build and preview production locally
+
+# Code Quality
+just check         # Run Biome linting and TypeScript checking
+just fix           # Auto-fix code formatting/lint issues
+```
+
+## Required
+
+- Dig into the root cause and fix it at the source. Never work around a fixable bug with a retry, sleep, or timeout.
+- Fail loud and early. Error on unsupported or malformed input rather than warn and continue.
+- Reproduce bugs before fixing them. Land each fix with a regression test that fails without it, when one is easy.
+- Keep the PR focused. No unrelated refactors, formatting churn, or drive-by changes; split when in doubt.
+- Refactor aggressively for long-term maintainability, but re-evaluate the direction as you learn.
+- Propose a course change, even suggest abandoning a PR, rather than finish a half-solution.
+- When a decision is the maintainer's (design, copy, naming, scope), ask with 2-3 options and a recommendation.
+- Never deploy to any environment, including staging, without the user's explicit permission for that deployment. A coding task or quest does not authorize a deploy.
+- Protocol, player, and publisher fixes belong upstream in moq-dev/moq (`@moq/publish`, `@moq/watch`, ...). Fix them there first, then bump the package here.
+- Never edit an `AGENTS.md`, `PROMPTING.md`, or skill without being prompted. Read `PROMPTING.md` before editing one or instructing other agents via context, memory, plans, or reviews.
+- No em dashes in code, comments, or agent-written prose.
+- Match the existing conventions, patterns, and naming when possible.
+- Fix any outdated docs and comments inline; don't add a separate PR for it.
+- Add the AI marker `(Written by <model>)` to any posts on GitHub, excluding commit messages that contain `Co-Authored-By:` trailers.
+- Any AI comments may be challenged, and not confused with human maintainers.
+
+## Guidelines
+
+- Comments should explain the non-obvious why, and never the history.
+- Inline simple helpers.
+- Question whether functionality is needed at all before adding it.
+- Deleting code is better than adding code.
+- Prefer the simple solution.
+- New dependencies use the newest stable version.
+- Say it once, in the fewest words that hold up.
+- Suggest follow up sessions and quests when finished, interactively prompting the user.
+- Prefer a quest over a GitHub issue for work needing durable scope.
+- Try to do stuff asynchronously. ex. ask about follow-ups while checks run.
+- If the core problem is addressed, ship it instead of spinning your wheels on meaningless revisions.
+
+## Development
+
+PRs target `main`. Before starting, `git fetch origin` and set the upstream to the base branch.
+`git stash` is one stack shared by every worktree; set work aside with a commit instead.
+Use the Nix dev shell (direnv, or `nix develop --command just ...`) so tooling matches CI.
+Run `just fix` before committing. `just check` alone is not verification: look at the change in the dev server.
+Quests: when work mentions a quest, run `quest guide` and follow it. The `quest` binary comes from the kixelated/quest flake input and serves the quest skills; change them upstream and bump the input.
+
+## Architecture Overview
+
+### Technology Stack
+- **Framework**: Astro (static output)
+- **UI Components**: Solid.js for interactive elements
+- **Styling**: Tailwind CSS
+- **Build**: Vite
+- **Code Quality**: Biome for linting/formatting
+- **Package Manager**: bun v1.3.13
+- **Task Runner**: just
+- **Toolchain**: pinned in `flake.nix`; `nix develop` (or direnv, via `.envrc`) provides bun, node, and just
+
+The Bun version in nixpkgs must match `packageManager` in `package.json`
+and the base image in `Dockerfile`. CI reads its version from `package.json`
+and evaluates the flake assertions to catch drift. When a weekly Dependabot
+Nix update changes Bun, update the other two pins in the same PR.
+
+### Key Components
+
+**MoQ Client Implementation** (`@moq/publish` + `@moq/watch` packages):
+   - Custom web components: `<moq-publish>`, `<moq-watch>`
+   - UI wrapper components: `<moq-publish-ui>`, `<moq-watch-ui>`
+
+### Important Patterns
+
+- **No REST APIs**: Uses WebTransport directly for streaming
+- **Stateless**: No database or user management
+- **Error Handling**: Component-level with `src/components/fail.tsx`
+- **Authentication**: Basic JWT support via query parameters for demo broadcasts
+- **Content Management**: MDX files in `src/pages/blog/` for documentation
+
+### The moq.pub / moq.watch URL scheme
+
+A broadcast is identified by its path: `/<project>/<name>`, e.g.
+`moq.pub/try/h2z15dgmdh.hang`. The project is the relay tenant and the
+name is everything after it, so names may contain slashes. The same path on
+either site refers to the same broadcast: publish at `moq.pub/try/x.hang` and
+watch it back at `moq.watch/try/x.hang`.
+
+Anything that *isn't* part of the broadcast's identity stays in the query
+string: `?relay=<url>`, `?cloudflare=<subdomain>`, `?jwt=<token>`, and
+(moq.pub only) `?source=camera`. `?cloudflare=draft-16` is shorthand for
+`https://draft-16.cloudflare.mediaoverquic.com`; the project path segment still
+carries Cloudflare's relay token. `cloudflare` and `relay` are mutually
+exclusive.
+
+A bare `moq.pub/` mints a private broadcast in the `try` project from
+`POST ${PUBLIC_API_URL}/try/token` and keeps the publish token in its own URL.
+**A watch link never carries `?jwt=`**: moq tokens are prefix-scoped with
+separate publish (`put`) and subscribe (`get`) grants, so a shared publish token
+lets anyone publish. moq.pub links to moq.watch only for `try` on the default
+relay, and moq.watch mints its own subscribe token from `/try/watch` for a
+tokenless `try` path. Other projects get no link; swap the hostname.
+
+`sites/lib` holds the scheme itself, shared by both sites and by both the Worker
+and the Vite dev server so they can't drift:
+
+- `broadcast.ts`: parse and build `/<project>/<name>`, and the relay URL
+- `route.ts`: old `?project=&name=` links redirect into the path
+- `try.ts`: mint `try` credentials from the API
+- `worker.ts`: the Worker both sites export
+- `dev.ts`: a Vite plugin giving `just dev-pub` / `just dev-watch` the same
+  routing (`just dev` is the Astro site and doesn't use it)
+
+Two things are easy to break here:
+
+- `assets.run_worker_first: ["/"]` in each `wrangler.jsonc` is load-bearing. `/`
+  matches `index.html`, so without it Cloudflare's asset server answers first and
+  the Worker never runs and old `?project=&name=` links don't redirect.
+- The Worker can't decide "asset vs. page" by looking for a dot, because names
+  end in `.hang`. It asks the asset store and falls back to the page on a 404.
+
+### Deployment
+
+- Cloudflare Workers via Wrangler, one per site
+- `just deploy` for staging, `just deploy live` for production
+- Deploys are manual; nothing ships on merge to `main`
+
+`just deploy <env>` builds all three sites in that mode and uploads each Worker.
+The player sites read the repo-root `.env.<env>` files that the Astro site uses,
+so `PUBLIC_RELAY_URL` is the single place the relay is configured. Staging is
+`new.moq.dev`, `new.moq.pub`, and `new.moq.watch`.
+
+The player sites deploy before moq.dev.
+
+## Development Tips
+
+- Broadcasts are ephemeral - no persistence layer
+- The `@moq/publish` and `@moq/watch` packages handle all MoQ protocol implementation
+- For new blog posts, add MDX files to `src/pages/blog/`
+- Component changes in `src/components/` automatically reload with HMR