{
  "name": "adventures-together-api-skill-pack",
  "version": "1.1.0",
  "description": "Agent-focused execution bundle for Adventures Together API v1.",
  "artifacts": {
    "openapi": "/api/v1/openapi",
    "openapiStatic": "/openapi/openapi.v1.json",
    "capabilities": "/api/v1/capabilities",
    "capabilitiesStatic": "/.well-known/api-capabilities.json",
    "accessMatrix": "/api/v1/access-matrix",
    "onboarding": "/docs/agent-onboarding.md",
    "apiImpactChecklist": "/docs/api-impact-checklist.md",
    "catalogResearchContract": "/docs/catalog-research-data-contract.md",
    "bucketListItemAuditPlaybook": "/docs/bucket-list-item-audit-playbook.md",
    "skills": {
      "codex": "/docs/skills/adventures-together-codex.SKILL.md",
      "claudeCode": "/docs/skills/adventures-together-claude.md",
      "openCode": "/docs/skills/adventures-together-opencode.md"
    }
  },
  "authentication": {
    "type": "bearer_api_key",
    "header": "Authorization",
    "format": "Bearer <api_key>"
  },
  "safeDefaults": {
    "sendRequestIdHeader": true,
    "requestIdHeader": "x-request-id",
    "traceHeader": "x-agent-debug",
    "idempotencyHeader": "Idempotency-Key",
    "retryPolicy": {
      "on429": "respect retry-after; fallback to x-ratelimit-reset; add jitter",
      "on409": "do not retry IDEMPOTENCY_KEY_REUSED with same key",
      "on403": "stop and escalate permission/tier mismatch",
      "on401": "refresh credentials before retry"
    }
  },
  "accessBoundaries": {
    "standardNow": [
      "Discover API artifacts, capabilities, usage, and access matrix",
      "Manage the agent's own API keys",
      "Read or write user/partnership data only for the requesting user's explicit workflow",
      "Create normal personal items, completions, and list entries with idempotency keys"
    ],
    "trustedLater": [
      "Add or update public/shared catalog and bucket-list content across all Together domains",
      "Run higher-volume content production after source-rights, image quality, and list-scope checks",
      "Attach reusable catalog research and rich content when canonical identity is clear"
    ],
    "approvalRequired": [
      "Admin / Operator governance, audit, security, tier override, production repair, and research packet replay",
      "Cross-user reads or writes and private partnership data outside the active user workflow",
      "Ambiguous source-rights, image-license, coordinate, identity, or canonical-link decisions",
      "Browser/admin actions requiring logged-in sessions, production data mutation, or external service credentials"
    ],
    "linearOwners": {
      "tierNaming": "AWY-101",
      "tierEscalation": "AWY-94",
      "adminOperatorModel": "AWY-108",
      "agentDocs": "AWY-112"
    }
  },
  "workflows": [
    {
      "id": "api-impact-review",
      "description": "Before implementing or closing substantial feature/admin/catalog/automation work, decide whether API parity, artifacts, tiers, docs, or security controls changed.",
      "readFirst": [
        "/docs/api-impact-checklist.md"
      ],
      "steps": [
        "Fill the API impact section in Linear",
        "Update OpenAPI, discovery, capabilities, CLI, SDK/docs, or access matrix when needed",
        "Run pnpm api:artifacts:check, pnpm api:route-inventory:check, and pnpm test:api-contract when API artifacts or route surface changed"
      ]
    },
    {
      "id": "discover-api",
      "description": "Fetch discovery payload and capability manifest before planning actions.",
      "steps": [
        "GET /api/v1",
        "GET /api/v1/capabilities",
        "GET /api/v1/openapi"
      ]
    },
    {
      "id": "first-success",
      "description": "Verify identity, effective access, usage limits, and one safe read before attempting writes.",
      "steps": [
        "GET /api/v1/me",
        "GET /api/v1/capabilities",
        "GET /api/v1/usage",
        "GET /api/v1/access-matrix",
        "Preserve requestId or x-request-id for support handoff",
        "GET /api/v1/bucket-lists?section=dream"
      ]
    },
    {
      "id": "request-elevated-access",
      "description": "When the API doctor says a workflow is blocked by tier, ask the user to submit an API Center access request with workflow, scope, volume, public-write, and admin/operator context.",
      "steps": [
        "Run CLI doctor or GET /api/v1/access-matrix",
        "Open /settings/api-keys",
        "Submit Request elevated access form",
        "Wait for admin review in /admin/api-keys"
      ]
    },
    {
      "id": "manage-keys",
      "description": "Create, list, rotate, revoke, rename, or delete API keys.",
      "steps": [
        "POST /api/v1/auth/register",
        "GET /api/v1/auth/keys",
        "PATCH /api/v1/auth/keys/:id",
        "DELETE /api/v1/auth/keys/:id",
        "POST /api/v1/auth/rotate",
        "DELETE /api/v1/auth/revoke"
      ]
    },
    {
      "id": "research-catalog-item",
      "description": "Attach reusable research metadata to a canonical catalog item.",
      "steps": [
        "PUT /api/v1/catalog/:section/:catalogTable/:catalogItemId/research",
        "PUT /api/v1/catalog/:section/:catalogTable/:catalogItemId/rich-content",
        "POST /api/v1/catalog/research/coverage"
      ]
    },
    {
      "id": "audit-bucket-list-items",
      "description": "Audit bucket-list membership, canonical links, images, sources, tags, and Learn More guides before applying public catalog changes.",
      "readFirst": [
        "/docs/bucket-list-item-audit-playbook.md",
        "/docs/catalog-research-data-contract.md"
      ],
      "steps": [
        "GET /api/v1/admin/bucket-list-research",
        "GET /api/v1/catalog/:section/:catalogTable/:catalogItemId/research",
        "PUT /api/v1/catalog/:section/:catalogTable/:catalogItemId/research",
        "PUT /api/v1/catalog/:section/:catalogTable/:catalogItemId/rich-content"
      ]
    },
    {
      "id": "admin-security-ops",
      "description": "Investigate and contain API abuse incidents.",
      "steps": [
        "GET /api/v1/admin/stats",
        "GET /api/v1/admin/access-requests",
        "PATCH /api/v1/admin/access-requests/:id",
        "GET /api/v1/admin/security-events",
        "GET /api/v1/admin/audit-logs",
        "POST /api/v1/admin/api-keys/:id/force-rotate",
        "PATCH /api/v1/admin/users/:id/api-access",
        "PATCH /api/v1/admin/users/:id/tier-override"
      ]
    }
  ],
  "cliReference": {
    "path": "tools/at-api-cli/at-api-cli.mjs",
    "recommendedCommands": [
      "discover",
      "capabilities",
      "doctor",
      "play-search",
      "dream-lists",
      "dream-create-list",
      "dream-add-item",
      "security-events",
      "audit-logs"
    ]
  },
  "tierGuide": {
    "trial": "Low-volume starter tier for discovery and key-management workflows.",
    "personal": "Standard self-serve tier for normal authenticated writes.",
    "contributor": "Trusted high-throughput tier that can add public/shared items across all 8 Together domains.",
    "admin": "Admin / Operator tier for full governance and security operations."
  }
}