availsync 0.1.0

package/frontend/lib/setupGuides.ts

@@ -0,0 +1,630 @@
+export type SetupSnippet = {
+  id: string;
+  title: string;
+  description: string;
+  code: string;
+  copyLabel: string;
+};
+
+export type SetupGuideInput = {
+  appUrl?: string;
+  agentId?: string;
+  resourceType?: 'project' | 'repo';
+  resourceKey?: string;
+  durationMinutes?: number;
+};
+
+export const resourceScopeNote =
+  'Use repo-level resources for maximum safety. Use project-level resources only for independent work streams; Availsync does not yet infer dependencies between different resources.';
+
+function values(input: SetupGuideInput) {
+  return {
+    appUrl: input.appUrl || 'https://availsync.dev',
+    agentId: input.agentId || 'AGENT_ID',
+    resourceType: input.resourceType || 'repo',
+    resourceKey: input.resourceKey || 'owner/repo',
+    durationMinutes: input.durationMinutes || 45,
+  };
+}
+
+export function mcpEnvSnippet(input: SetupGuideInput = {}): SetupSnippet {
+  const { appUrl, agentId } = values(input);
+  return {
+    id: 'mcp-env',
+    title: 'MCP environment',
+    description: 'Store these values in your MCP or server environment. The API key is a runtime secret.',
+    copyLabel: 'Copy MCP env',
+    code: `AVAILSYNC_API_URL=${appUrl}
+AVAILSYNC_AGENT_ID=${agentId}
+AVAILSYNC_API_KEY=API_KEY`,
+  };
+}
+
+export function claudeCursorSnippet(input: SetupGuideInput = {}): SetupSnippet {
+  const { appUrl, agentId } = values(input);
+  return {
+    id: 'claude-cursor-mcp',
+    title: 'Claude or Cursor MCP config',
+    description: 'Use the public stdio MCP package with environment variables. Replace API_KEY in your local secret store.',
+    copyLabel: 'Copy MCP config',
+    code: `{
+  "mcpServers": {
+    "availsync": {
+      "command": "npx",
+      "args": ["-y", "@availsync/mcp@alpha"],
+      "env": {
+        "AVAILSYNC_API_URL": "${appUrl}",
+        "AVAILSYNC_AGENT_ID": "${agentId}",
+        "AVAILSYNC_API_KEY": "API_KEY"
+      }
+    }
+  }
+}`,
+  };
+}
+
+export function codexMcpSetupSnippet(input: SetupGuideInput = {}): SetupSnippet {
+  const { appUrl, agentId } = values(input);
+  return {
+    id: 'codex-mcp-fields',
+    title: 'Codex app MCP server fields',
+    description: 'In Codex, open Settings -> MCP servers -> Add server, then fill the fields below. Keep API_KEY as a secret value from create or rotate key.',
+    copyLabel: 'Copy Codex MCP fields',
+    code: `Name
+Availsync
+
+Command
+npx
+
+Arguments
+-y @availsync/mcp@alpha
+
+Transport
+stdio
+
+Working directory
+Leave empty
+
+Environment variables
+AVAILSYNC_API_URL=${appUrl}
+AVAILSYNC_AGENT_ID=${agentId}
+AVAILSYNC_API_KEY=API_KEY`,
+  };
+}
+
+export function codexMultiAgentMcpSnippet(input: SetupGuideInput = {}): SetupSnippet {
+  const { appUrl } = values(input);
+  return {
+    id: 'codex-multi-agent-mcp',
+    title: 'Multiple Codex sessions or roles',
+    description: 'Use one MCP server entry per Availsync agent when you want role-specific priorities, for example builder and reviewer. Each role needs its own agent id and one-time API key.',
+    copyLabel: 'Copy multi-agent Codex TOML',
+    code: `[mcp_servers.availsync_builder]
+command = "cmd"
+args = ["/c", "npx", "-y", "@availsync/mcp@alpha"]
+enabled = true
+
+[mcp_servers.availsync_builder.env]
+AVAILSYNC_API_URL = "${appUrl}"
+AVAILSYNC_AGENT_ID = "BUILDER_AGENT_ID"
+AVAILSYNC_API_KEY = "BUILDER_API_KEY"
+
+[mcp_servers.availsync_reviewer]
+command = "cmd"
+args = ["/c", "npx", "-y", "@availsync/mcp@alpha"]
+enabled = true
+
+[mcp_servers.availsync_reviewer.env]
+AVAILSYNC_API_URL = "${appUrl}"
+AVAILSYNC_AGENT_ID = "REVIEWER_AGENT_ID"
+AVAILSYNC_API_KEY = "REVIEWER_API_KEY"`,
+  };
+}
+
+export function workGuardrailSnippets(input: SetupGuideInput = {}): SetupSnippet[] {
+  const { appUrl, agentId, resourceType, resourceKey, durationMinutes } = values(input);
+  return [
+    {
+      id: 'work-check',
+      title: 'Check work slot',
+      description: `Call this before a coding agent starts. Default to repo-level scope unless the work stream is independent. ${resourceScopeNote}`,
+      copyLabel: 'Copy check curl',
+      code: `curl -X POST "${appUrl}/v1/work/check" \\
+  -H "Authorization: Bearer API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d '{"agent_id":"${agentId}","resource_type":"${resourceType}","resource_key":"${resourceKey}","duration_minutes":${durationMinutes},"reason":"pre-flight coding run"}'`,
+    },
+    {
+      id: 'work-claim',
+      title: 'Claim before work',
+      description: 'Claim the repo with an idempotency key so retries do not create duplicate active claims.',
+      copyLabel: 'Copy claim curl',
+      code: `curl -X POST "${appUrl}/v1/work/claim" \\
+  -H "Authorization: Bearer API_KEY" \\
+  -H "Idempotency-Key: coding-run-${resourceKey.replace(/[^a-zA-Z0-9]/g, '-')}-$(date +%Y%m%d%H)" \\
+  -H "Content-Type: application/json" \\
+  -d '{"agent_id":"${agentId}","resource_type":"${resourceType}","resource_key":"${resourceKey}","duration_minutes":${durationMinutes},"reason":"coding agent run"}'`,
+    },
+    {
+      id: 'work-extend',
+      title: 'Extend while running',
+      description: 'Call this before expires_at if the agent is still working.',
+      copyLabel: 'Copy extend curl',
+      code: `curl -X POST "${appUrl}/v1/work/claims/CLAIM_ID/extend" \\
+  -H "Authorization: Bearer API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d '{"duration_minutes":45}'`,
+    },
+    {
+      id: 'work-release',
+      title: 'Release when done',
+      description: 'Always release the claim when the agent finishes or exits cleanly.',
+      copyLabel: 'Copy release curl',
+      code: `curl -X DELETE "${appUrl}/v1/work/claims/CLAIM_ID" \\
+  -H "Authorization: Bearer API_KEY"`,
+    },
+  ];
+}
+
+export function automationGuardrailSnippets(input: SetupGuideInput = {}): SetupSnippet[] {
+  const { appUrl, agentId, resourceType, resourceKey, durationMinutes } = values(input);
+  const safeKey = resourceKey.replace(/[^a-zA-Z0-9]/g, '-');
+  return [
+    {
+      id: 'automation-shell',
+      title: 'Shell guardrail wrapper',
+      description: `Use run/start before work and always call run/finish from a trap when a claim was created. ${resourceScopeNote}`,
+      copyLabel: 'Copy shell wrapper',
+      code: `#!/usr/bin/env bash
+set -euo pipefail
+
+API_URL="${appUrl}"
+AGENT_ID="${agentId}"
+RESOURCE_TYPE="${resourceType}"
+RESOURCE_KEY="${resourceKey}"
+IDEMPOTENCY_KEY="automation-${safeKey}-$(date +%Y%m%d%H)"
+CLAIM_ID=""
+
+finish_claim() {
+  if [ -n "$CLAIM_ID" ]; then
+    curl -fsS -X POST "$API_URL/v1/work/run/finish" \\
+      -H "Authorization: Bearer $AVAILSYNC_API_KEY" \\
+      -H "Content-Type: application/json" \\
+      -d "{\\"claim_id\\":\\"$CLAIM_ID\\",\\"outcome\\":\\"finished\\"}" >/dev/null || true
+  fi
+}
+trap finish_claim EXIT
+
+START_RESPONSE=$(curl -fsS -X POST "$API_URL/v1/work/run/start" \\
+  -H "Authorization: Bearer $AVAILSYNC_API_KEY" \\
+  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d "{\\"agent_id\\":\\"$AGENT_ID\\",\\"resource_type\\":\\"$RESOURCE_TYPE\\",\\"resource_key\\":\\"$RESOURCE_KEY\\",\\"duration_minutes\\":${durationMinutes},\\"reason\\":\\"scheduled coding automation\\"}")
+
+ACTION=$(node -e "const r=JSON.parse(process.argv[1]); console.log(r.action)" "$START_RESPONSE")
+if [ "$ACTION" = "skip_run" ]; then
+  node -e "const r=JSON.parse(process.argv[1]); console.log(r.reason)" "$START_RESPONSE"
+  exit 0
+fi
+
+CLAIM_ID=$(node -e "const r=JSON.parse(process.argv[1]); console.log(r.claim.id)" "$START_RESPONSE")
+
+# Run the coding agent command here.
+# codex exec "...your task..."
+`,
+    },
+    {
+      id: 'automation-github-actions',
+      title: 'GitHub Actions step',
+      description: 'Put Availsync secrets in repository or organization secrets and skip cleanly when another agent owns the repo.',
+      copyLabel: 'Copy Actions step',
+      code: `- name: Start Availsync guarded run
+  id: availsync
+  env:
+    AVAILSYNC_API_KEY: \${{ secrets.AVAILSYNC_API_KEY }}
+  run: |
+    RESPONSE=$(curl -fsS -X POST "${appUrl}/v1/work/run/start" \\
+      -H "Authorization: Bearer $AVAILSYNC_API_KEY" \\
+      -H "Idempotency-Key: github-\${{ github.run_id }}" \\
+      -H "Content-Type: application/json" \\
+      -d '{"agent_id":"${agentId}","resource_type":"${resourceType}","resource_key":"${resourceKey}","duration_minutes":${durationMinutes},"reason":"GitHub Actions coding automation"}')
+    echo "action=$(node -e 'const r=JSON.parse(process.argv[1]); console.log(r.action)' "$RESPONSE")" >> "$GITHUB_OUTPUT"
+    echo "claim_id=$(node -e 'const r=JSON.parse(process.argv[1]); console.log(r.claim?.id || "")' "$RESPONSE")" >> "$GITHUB_OUTPUT"
+
+- name: Finish Availsync guarded run
+  if: always() && steps.availsync.outputs.claim_id != ''
+  env:
+    AVAILSYNC_API_KEY: \${{ secrets.AVAILSYNC_API_KEY }}
+  run: |
+    curl -fsS -X POST "${appUrl}/v1/work/run/finish" \\
+      -H "Authorization: Bearer $AVAILSYNC_API_KEY" \\
+      -H "Content-Type: application/json" \\
+      -d '{"claim_id":"\${{ steps.availsync.outputs.claim_id }}","outcome":"finished"}'`,
+    },
+    {
+      id: 'automation-codex-prompt',
+      title: 'Codex automation prompt',
+      description: 'Use this in a scheduled Codex run so the agent respects the shared repo claim before editing.',
+      copyLabel: 'Copy Codex prompt',
+      code: `Before changing files, start an Availsync guarded run.
+
+Use:
+- API URL: ${appUrl}
+- Agent ID: ${agentId}
+- Resource: ${resourceType}:${resourceKey}
+
+Resource scope:
+- Safe default: repo:owner/repo means one active agent can work in the repo.
+- Advanced: project:homepage allows parallel work only when it does not depend on other active project work.
+
+Call POST /v1/work/run/start with an Idempotency-Key for this run.
+If action is "skip_run", stop and report the reason.
+If action is "proceed", keep the claim id, extend with /v1/work/run/extend if work continues near expiry, and always call /v1/work/run/finish before ending.`,
+    },
+    {
+      id: 'automation-server-worker',
+      title: 'Server worker flow',
+      description: 'Use this shape in cron, queue workers, deploy bots, or hosted scheduled jobs.',
+      copyLabel: 'Copy worker flow',
+      code: `POST ${appUrl}/v1/work/run/start
+Authorization: Bearer API_KEY
+Idempotency-Key: worker-${safeKey}-RUN_ID
+
+{
+  "agent_id": "${agentId}",
+  "resource_type": "${resourceType}",
+  "resource_key": "${resourceKey}",
+  "duration_minutes": ${durationMinutes},
+  "reason": "server-side automation"
+}
+
+If action === "skip_run": exit 0 with reason.
+If action === "proceed": run work, call /v1/work/run/extend while active, then /v1/work/run/finish in finally.`,
+    },
+  ];
+}
+
+export function nodeSdkSnippets(input: SetupGuideInput = {}): SetupSnippet[] {
+  const { agentId, resourceKey, durationMinutes } = values(input);
+  const safeKey = resourceKey.replace(/[^a-zA-Z0-9]/g, '-');
+  return [
+    {
+      id: 'node-sdk-basic',
+      title: 'Basic guarded run',
+      description: 'Use the SDK helper when your app should run work only after Availsync claims the repo.',
+      copyLabel: 'Copy SDK example',
+      code: `import { createAvailsyncClient } from '@availsync/node';
+
+const availsync = createAvailsyncClient({
+  apiKey: process.env.AVAILSYNC_API_KEY!,
+  agentId: process.env.AVAILSYNC_AGENT_ID!,
+  baseUrl: process.env.AVAILSYNC_API_URL,
+});
+
+const result = await availsync.work.withClaim(
+  'repo:${resourceKey}',
+  { reason: 'coding-agent run', durationMinutes: ${durationMinutes} },
+  async ({ claim, shadow }) => {
+    if (shadow.wouldHaveBlocked) {
+      console.warn('Observe-only: Availsync would have skipped this run.');
+    }
+    const extendTimer = claim
+      ? setInterval(() => claim.extend({ durationMinutes: ${durationMinutes} }).catch(console.error), (${durationMinutes} - 5) * 60_000)
+      : null;
+    try {
+      await doWork();
+    } finally {
+      if (extendTimer) clearInterval(extendTimer);
+    }
+  },
+);
+
+if (result.action === 'skip_run') {
+  console.log(result.reason);
+}`,
+    },
+    {
+      id: 'node-sdk-codex',
+      title: 'Scheduled Codex run',
+      description: 'Wrap a scheduled Codex task so it exits cleanly when another agent owns the repo.',
+      copyLabel: 'Copy Codex SDK example',
+      code: `import { createAvailsyncClient } from '@availsync/node';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+
+const availsync = createAvailsyncClient({
+  apiKey: process.env.AVAILSYNC_API_KEY!,
+  agentId: '${agentId}',
+  baseUrl: process.env.AVAILSYNC_API_URL,
+});
+
+const result = await availsync.work.withClaim(
+  'repo:${resourceKey}',
+  {
+    reason: 'scheduled Codex automation',
+    durationMinutes: ${durationMinutes},
+    idempotencyKey: \`codex-${safeKey}-\${new Date().toISOString().slice(0, 13)}\`,
+  },
+  async ({ shadow }) => {
+    if (shadow.wouldHaveBlocked) {
+      console.warn('Observe-only: Availsync would have skipped this Codex run.');
+    }
+    const child = spawn('codex', ['exec', 'run the scheduled maintenance task'], { stdio: 'inherit' });
+    const [code] = await once(child, 'exit');
+    if (code !== 0) throw new Error(\`codex exited with \${code}\`);
+  },
+);
+
+if (result.action === 'skip_run') process.exit(0);`,
+    },
+    {
+      id: 'node-sdk-github-actions',
+      title: 'GitHub Actions step',
+      description: 'Install the SDK in your automation project and use GitHub run id as the idempotency key.',
+      copyLabel: 'Copy Actions SDK step',
+      code: `- name: Run guarded agent task
+  env:
+    AVAILSYNC_API_KEY: \${{ secrets.AVAILSYNC_API_KEY }}
+    AVAILSYNC_AGENT_ID: ${agentId}
+    AVAILSYNC_API_URL: ${values(input).appUrl}
+  run: |
+    npm install @availsync/node@alpha
+    node ./scripts/guarded-agent-run.mjs
+
+# scripts/guarded-agent-run.mjs
+import { createAvailsyncClient } from '@availsync/node';
+
+const availsync = createAvailsyncClient({
+  apiKey: process.env.AVAILSYNC_API_KEY,
+  agentId: process.env.AVAILSYNC_AGENT_ID,
+  baseUrl: process.env.AVAILSYNC_API_URL,
+});
+
+const result = await availsync.work.withClaim(
+  'repo:${resourceKey}',
+  {
+    reason: 'GitHub Actions coding automation',
+    idempotencyKey: \`github-\${process.env.GITHUB_RUN_ID}\`,
+  },
+  async ({ claim, shadow }) => {
+    if (shadow.wouldHaveBlocked) {
+      console.warn('Observe-only: Availsync would have skipped this run.');
+    }
+    const extendTimer = claim
+      ? setInterval(() => claim.extend({ durationMinutes: ${durationMinutes} }).catch(console.error), (${durationMinutes} - 5) * 60_000)
+      : null;
+    try {
+    // Run the coding agent command here.
+    } finally {
+      if (extendTimer) clearInterval(extendTimer);
+    }
+  },
+);
+
+if (result.action === 'skip_run') process.exit(0);`,
+    },
+    {
+      id: 'node-sdk-manual-extend',
+      title: 'Manual long-running flow',
+      description: 'Use start, extend, and finish directly when you need more control than withClaim.',
+      copyLabel: 'Copy manual SDK flow',
+      code: `const started = await availsync.work.start({
+  resource: 'repo:${resourceKey}',
+  reason: 'long-running agent run',
+  durationMinutes: ${durationMinutes},
+  idempotencyKey: \`agent-${safeKey}-\${Date.now()}\`,
+});
+
+if (started.action === 'skip_run') {
+  console.log(started.reason);
+  process.exit(0);
+}
+
+if (started.shadow_mode && started.would_have_blocked) {
+  console.warn('Observe-only: Availsync would have skipped this run.');
+}
+
+try {
+  if (started.claim) {
+    // Extend before expiry while the long-running task is still active.
+    await availsync.work.extend(started.claim.id, { durationMinutes: 45 });
+  }
+  await doWork();
+} finally {
+  if (started.claim) {
+    await availsync.work.finish(started.claim.id, { outcome: 'finished' });
+  }
+}`,
+    },
+  ];
+}
+
+export function openClawSkillSnippet(input: SetupGuideInput = {}): SetupSnippet {
+  const { appUrl, agentId, resourceType, resourceKey, durationMinutes } = values(input);
+  return {
+    id: 'openclaw-skill-md',
+    title: 'OpenClaw SKILL.md',
+    description: 'Install this as an OpenClaw skill so the agent claims the repo before it edits files.',
+    copyLabel: 'Copy SKILL.md',
+    code: `---
+name: availsync-guardrail
+description: Use before coding, repo edits, scheduled automations, deploy work, migrations, or other agent work that must not overlap with another agent. Coordinates through Availsync work run endpoints and prevents the agent from touching the same selected resource while another claim is active.
+---
+
+# Availsync Guardrail
+
+Use Availsync before changing files, running deploys, editing a repo, or starting long-running project work.
+
+## Required environment
+
+- AVAILSYNC_API_URL: ${appUrl}
+- AVAILSYNC_AGENT_ID: ${agentId}
+- AVAILSYNC_API_KEY: runtime secret, never write it into files or chat
+- AVAILSYNC_RESOURCE_TYPE: ${resourceType}
+- AVAILSYNC_RESOURCE_KEY: ${resourceKey}
+
+## Resource scope
+
+Use AVAILSYNC_RESOURCE_TYPE=repo and AVAILSYNC_RESOURCE_KEY=owner/repo for maximum safety. That allows only one active agent in the repo.
+
+Use project-level resources only for independent work streams. Availsync does not yet infer that project:homepage depends on project:product-catalog.
+
+## Workflow
+
+1. Before making changes, call POST /v1/work/run/start.
+2. Send Authorization: Bearer $AVAILSYNC_API_KEY and an Idempotency-Key for the current run.
+3. Include client_name: "openclaw" in the JSON body.
+4. If response action is "skip_run", stop immediately and report the reason. Do not edit files.
+5. If response action is "proceed", keep the claim id and do the requested work.
+6. If work continues near expires_at, call POST /v1/work/run/extend with the claim id.
+7. Always call POST /v1/work/run/finish before ending, including after errors or no-op runs.
+
+## Start request
+
+curl -fsS -X POST "$AVAILSYNC_API_URL/v1/work/run/start" \\
+  -H "Authorization: Bearer $AVAILSYNC_API_KEY" \\
+  -H "Idempotency-Key: openclaw-$(date +%Y%m%d%H%M%S)" \\
+  -H "Content-Type: application/json" \\
+  -d '{"agent_id":"'$AVAILSYNC_AGENT_ID'","resource_type":"'$AVAILSYNC_RESOURCE_TYPE'","resource_key":"'$AVAILSYNC_RESOURCE_KEY'","duration_minutes":${durationMinutes},"reason":"OpenClaw guarded run","client_name":"openclaw"}'
+
+## Finish request
+
+curl -fsS -X POST "$AVAILSYNC_API_URL/v1/work/run/finish" \\
+  -H "Authorization: Bearer $AVAILSYNC_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d '{"claim_id":"CLAIM_ID","outcome":"finished","client_name":"openclaw"}'
+
+## Failure policy
+
+If Availsync is unreachable, authentication fails, or the start response cannot be parsed, stop without editing files. Never continue unguarded.`,
+  };
+}
+
+export function openClawSetupSnippet(input: SetupGuideInput = {}): SetupSnippet {
+  const { appUrl, agentId, resourceType, resourceKey } = values(input);
+  return {
+    id: 'openclaw-setup',
+    title: 'OpenClaw setup',
+    description: 'Create the skill folder, paste SKILL.md, and keep secrets in environment variables.',
+    copyLabel: 'Copy OpenClaw setup',
+    code: `mkdir -p ~/.openclaw/skills/availsync-guardrail
+$EDITOR ~/.openclaw/skills/availsync-guardrail/SKILL.md
+
+export AVAILSYNC_API_URL="${appUrl}"
+export AVAILSYNC_AGENT_ID="${agentId}"
+export AVAILSYNC_API_KEY="API_KEY"
+export AVAILSYNC_RESOURCE_TYPE="${resourceType}"
+export AVAILSYNC_RESOURCE_KEY="${resourceKey}"
+
+# Resource scope:
+# - repo + owner/repo is the safest default: one active agent per repo.
+# - project + homepage allows parallel work only when streams are independent.
+# - Availsync does not yet infer dependencies between different resources.
+
+# Test after installing:
+# 1. Ask OpenClaw to use Availsync before editing this repo.
+# 2. Confirm Activity shows client "openclaw".
+# 3. Confirm blocked runs stop with skip_run instead of editing files.`,
+  };
+}
+
+export function schedulingSnippets(input: SetupGuideInput = {}): SetupSnippet[] {
+  const { appUrl, agentId } = values(input);
+  return [
+    {
+      id: 'availability-check',
+      title: 'Check availability',
+      description: 'Ask Availsync for open slots before touching a calendar or downstream booking tool.',
+      copyLabel: 'Copy availability curl',
+      code: `curl "${appUrl}/v1/availability?agent_id=${agentId}&from=NEXT_BUSINESS_DAY_START&to=NEXT_BUSINESS_DAY_END&duration_minutes=30" \\
+  -H "Authorization: Bearer API_KEY"`,
+    },
+    {
+      id: 'conflict-preview',
+      title: 'Preview conflict',
+      description: 'Preview the decision and explanation before creating a hold.',
+      copyLabel: 'Copy preview curl',
+      code: `curl -X POST "${appUrl}/v1/conflicts/check" \\
+  -H "Authorization: Bearer API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d '{"agent_id":"${agentId}","start_at":"NEXT_BUSINESS_DAY_START","end_at":"NEXT_BUSINESS_DAY_SLOT_END","reason":"demo booking"}'`,
+    },
+    {
+      id: 'hold-create',
+      title: 'Create hold',
+      description: 'Create a hold only after availability and conflict preview pass.',
+      copyLabel: 'Copy hold curl',
+      code: `curl -X POST "${appUrl}/v1/holds" \\
+  -H "Authorization: Bearer API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d '{"agent_id":"${agentId}","start_at":"NEXT_BUSINESS_DAY_START","end_at":"NEXT_BUSINESS_DAY_SLOT_END","reason":"demo booking"}'`,
+    },
+  ];
+}
+
+export function codexPromptSnippet(input: SetupGuideInput = {}): SetupSnippet {
+  const { agentId, resourceKey } = values(input);
+  return {
+    id: 'codex-prompt',
+    title: 'Codex automation prompt',
+    description: 'Paste this into a scheduled coding-agent run so it respects Availsync before editing.',
+    copyLabel: 'Copy prompt',
+    code: `Before changing files, use Availsync.
+
+Agent id: ${agentId}
+Protected repo: ${resourceKey}
+
+Resource scope:
+- Safe default: claim repo:${resourceKey} so only one active agent can work in the repo.
+- Advanced: use project-level resources only when work streams are independent.
+
+1. Call check_work_slot for ${resourceKey}.
+2. If the response is would_lose or blocked, stop and report the blocking claim.
+3. If available or would_win, call claim_work_slot with an idempotency key for this run.
+4. While working, extend_work_slot before expires_at if more time is needed.
+5. Release the claim when finished, even if no code changes were made.`,
+  };
+}
+
+export function serverCronSnippet(input: SetupGuideInput = {}): SetupSnippet {
+  const { appUrl, agentId, resourceType, resourceKey, durationMinutes } = values(input);
+  return {
+    id: 'server-cron',
+    title: 'Server or cron pre-flight',
+    description: 'Use run/start in scheduled jobs so blocked runs skip cleanly instead of failing the job.',
+    copyLabel: 'Copy script',
+    code: `#!/usr/bin/env bash
+set -euo pipefail
+
+API_URL="${appUrl}"
+AGENT_ID="${agentId}"
+RESOURCE_TYPE="${resourceType}"
+RESOURCE_KEY="${resourceKey}"
+
+curl -fsS -X POST "$API_URL/v1/work/run/start" \\
+  -H "Authorization: Bearer $AVAILSYNC_API_KEY" \\
+  -H "Idempotency-Key: cron-${resourceKey.replace(/[^a-zA-Z0-9]/g, '-')}-$(date +%Y%m%d%H)" \\
+  -H "Content-Type: application/json" \\
+  -d "{\\"agent_id\\":\\"$AGENT_ID\\",\\"resource_type\\":\\"$RESOURCE_TYPE\\",\\"resource_key\\":\\"$RESOURCE_KEY\\",\\"duration_minutes\\":${durationMinutes}}"`,
+  };
+}
+
+export function quickstartUseCases() {
+  return [
+    {
+      title: 'Stop two coding agents from working on the same repo',
+      body:
+        'Each agent checks and claims owner/repo before it starts. If another claim is active, the next run skips with a clear reason instead of touching the same files.',
+    },
+    {
+      title: 'Coordinate server automations before they run',
+      body:
+        'Deploys, migrations, review passes, cron jobs, and cleanup scripts can use the same repo claims as coding agents.',
+    },
+    {
+      title: 'Also coordinate scheduling tools before they book',
+      body:
+        'Scheduling agents can check availability, preview conflicts, create holds, and release them through the same priority and audit layer.',
+    },
+  ];
+}

package/frontend/lib/storage.ts

@@ -0,0 +1,30 @@
+export type StoredSession = {
+  orgId: string;
+  userId: string;
+  email: string;
+};
+
+const KEY = 'availsync_session';
+
+export function saveSession(session: StoredSession): void {
+  if (typeof window === 'undefined') return;
+  window.localStorage.setItem(KEY, JSON.stringify(session));
+}
+
+export function loadSession(): StoredSession | null {
+  if (typeof window === 'undefined') return null;
+  const raw = window.localStorage.getItem(KEY);
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw) as Partial<StoredSession>;
+    if (!parsed.orgId || !parsed.userId || !parsed.email) return null;
+    return parsed as StoredSession;
+  } catch {
+    return null;
+  }
+}
+
+export function clearSession(): void {
+  if (typeof window === 'undefined') return;
+  window.localStorage.removeItem(KEY);
+}

package/frontend/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+/// <reference path="./.next/types/routes.d.ts" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/frontend/next.config.mjs

@@ -0,0 +1,13 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  output: 'standalone',
+  outputFileTracingRoot: __dirname,
+  devIndicators: false,
+};
+
+export default nextConfig;