[
  {
    "method": "GET",
    "path": "/actors",
    "description": "List all registered actor sessions with their last-seen timestamp and pending notification count",
    "auth": "viewer",
    "actors": [
      "developer",
      "admin"
    ],
    "params": [
      {
        "name": "project",
        "kind": "string",
        "constraint": "optional",
        "description": "Filter by project slug"
      }
    ],
    "tags": [
      "actors"
    ],
    "feature": ""
  },
  {
    "method": "POST",
    "path": "/actors/register",
    "description": "Register an actor session and receive a bearer token for subsequent calls",
    "auth": "none",
    "actors": [
      "agent",
      "developer",
      "ci"
    ],
    "params": [
      {
        "name": "actor",
        "kind": "string",
        "constraint": "required",
        "description": "Actor type (agent|developer|ci|admin)"
      },
      {
        "name": "project",
        "kind": "string",
        "constraint": "optional",
        "description": "Project slug to associate with"
      },
      {
        "name": "label",
        "kind": "string",
        "constraint": "optional",
        "description": "Human label for audit trail"
      }
    ],
    "tags": [
      "actors",
      "auth"
    ],
    "feature": ""
  },
  {
    "method": "DELETE",
    "path": "/actors/{token}",
    "description": "Deregister an actor session and invalidate its bearer token",
    "auth": "none",
    "actors": [
      "agent",
      "developer",
      "ci"
    ],
    "params": [],
    "tags": [
      "actors",
      "auth"
    ],
    "feature": ""
  },
  {
    "method": "POST",
    "path": "/actors/{token}/profile",
    "description": "Update actor profile metadata: display name, role, and custom context fields",
    "auth": "none",
    "actors": [
      "agent",
      "developer"
    ],
    "params": [],
    "tags": [
      "actors"
    ],
    "feature": ""
  },
  {
    "method": "POST",
    "path": "/actors/{token}/touch",
    "description": "Extend actor session TTL; prevents the session from expiring due to inactivity",
    "auth": "none",
    "actors": [
      "agent",
      "developer",
      "ci"
    ],
    "params": [],
    "tags": [
      "actors"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/adr/{id}",
    "description": "Read a single ADR by id, exported from NCL as structured JSON",
    "auth": "none",
    "actors": [
      "agent",
      "developer"
    ],
    "params": [
      {
        "name": "slug",
        "kind": "string",
        "constraint": "optional",
        "description": "Project slug (defaults to primary)"
      }
    ],
    "tags": [
      "adrs"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/api/catalog",
    "description": "Full catalog of daemon HTTP endpoints with metadata: auth, actors, params, tags",
    "auth": "none",
    "actors": [
      "agent",
      "developer",
      "ci",
      "admin"
    ],
    "params": [],
    "tags": [
      "meta",
      "catalog"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/backlog-json",
    "description": "Export the project backlog as structured JSON from reflection/backlog.ncl",
    "auth": "viewer",
    "actors": [
      "developer",
      "agent"
    ],
    "params": [
      {
        "name": "slug",
        "kind": "string",
        "constraint": "optional",
        "description": "Project slug (defaults to primary)"
      }
    ],
    "tags": [
      "backlog"
    ],
    "feature": ""
  },
  {
    "method": "POST",
    "path": "/cache/invalidate",
    "description": "Invalidate one or all NCL cache entries, forcing re-export on next request",
    "auth": "admin",
    "actors": [
      "developer",
      "admin"
    ],
    "params": [
      {
        "name": "file",
        "kind": "string",
        "constraint": "optional",
        "description": "Specific file path to invalidate (omit to invalidate all)"
      }
    ],
    "tags": [
      "cache"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/cache/stats",
    "description": "NCL export cache statistics: entry count, hit/miss counters",
    "auth": "viewer",
    "actors": [
      "developer",
      "admin"
    ],
    "params": [],
    "tags": [
      "cache",
      "meta"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/config/cross-project",
    "description": "Compare config surfaces across all registered projects: shared values, conflicts, coverage gaps",
    "auth": "none",
    "actors": [
      "agent",
      "developer"
    ],
    "params": [],
    "tags": [
      "config"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/describe/actor-init",
    "description": "Minimal onboarding payload for a new actor session: what to register as and what to do first",
    "auth": "none",
    "actors": [
      "agent"
    ],
    "params": [
      {
        "name": "actor",
        "kind": "string",
        "constraint": "optional",
        "description": "Actor type to onboard as"
      },
      {
        "name": "slug",
        "kind": "string",
        "constraint": "optional",
        "description": "Project slug"
      }
    ],
    "tags": [
      "describe",
      "actors"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/describe/capabilities",
    "description": "Available reflection modes, just recipes, Claude capabilities and CI tools for the project",
    "auth": "none",
    "actors": [
      "agent",
      "developer",
      "ci"
    ],
    "params": [
      {
        "name": "slug",
        "kind": "string",
        "constraint": "optional",
        "description": "Project slug (defaults to primary)"
      }
    ],
    "tags": [
      "describe"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/describe/connections",
    "description": "Cross-project connection declarations: upstream, downstream, peers with addressing",
    "auth": "none",
    "actors": [
      "agent",
      "developer"
    ],
    "params": [
      {
        "name": "slug",
        "kind": "string",
        "constraint": "optional",
        "description": "Project slug (defaults to primary)"
      }
    ],
    "tags": [
      "describe",
      "federation"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/describe/guides",
    "description": "Complete operational context for an actor: identity, axioms, practices, constraints, gate state, modes, actor policy, connections, content assets",
    "auth": "none",
    "actors": [
      "agent",
      "developer",
      "ci"
    ],
    "params": [
      {
        "name": "slug",
        "kind": "string",
        "constraint": "optional",
        "description": "Project slug (defaults to primary)"
      },
      {
        "name": "actor",
        "kind": "string",
        "constraint": "optional",
        "description": "Actor context filters the policy (agent|developer|ci|admin)"
      }
    ],
    "tags": [
      "describe",
      "guides"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/describe/project",
    "description": "Project self-description: identity, axioms, tensions, practices, gates, ADRs, dimensions",
    "auth": "none",
    "actors": [
      "agent",
      "developer",
      "ci",
      "admin"
    ],
    "params": [
      {
        "name": "slug",
        "kind": "string",
        "constraint": "optional",
        "description": "Project slug (defaults to primary)"
      }
    ],
    "tags": [
      "describe",
      "ontology"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/graph/impact",
    "description": "BFS impact graph from an ontology node; optionally traverses cross-project connections",
    "auth": "none",
    "actors": [
      "agent",
      "developer"
    ],
    "params": [
      {
        "name": "node",
        "kind": "string",
        "constraint": "required",
        "description": "Ontology node id to start from"
      },
      {
        "name": "depth",
        "kind": "u32",
        "constraint": "default=2",
        "description": "Max BFS hops (capped at 5)"
      },
      {
        "name": "include_external",
        "kind": "bool",
        "constraint": "default=false",
        "description": "Follow connections.ncl to external projects"
      },
      {
        "name": "slug",
        "kind": "string",
        "constraint": "optional",
        "description": "Project slug (defaults to primary)"
      }
    ],
    "tags": [
      "graph",
      "federation"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/graph/node/{id}",
    "description": "Resolve a single ontology node by id from the local cache (used by federation)",
    "auth": "none",
    "actors": [
      "agent",
      "developer"
    ],
    "params": [
      {
        "name": "slug",
        "kind": "string",
        "constraint": "optional",
        "description": "Project slug (defaults to primary)"
      }
    ],
    "tags": [
      "graph",
      "federation"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/health",
    "description": "Daemon health check: uptime, version, feature flags, active projects",
    "auth": "none",
    "actors": [
      "agent",
      "developer",
      "ci",
      "admin"
    ],
    "params": [],
    "tags": [
      "meta"
    ],
    "feature": ""
  },
  {
    "method": "POST",
    "path": "/nickel/export",
    "description": "Export a Nickel file to JSON, using the cache when the file is unchanged",
    "auth": "viewer",
    "actors": [
      "developer",
      "agent"
    ],
    "params": [
      {
        "name": "file",
        "kind": "string",
        "constraint": "required",
        "description": "Absolute path to the .ncl file to export"
      },
      {
        "name": "import_path",
        "kind": "string",
        "constraint": "optional",
        "description": "NICKEL_IMPORT_PATH override"
      }
    ],
    "tags": [
      "nickel",
      "cache"
    ],
    "feature": ""
  },
  {
    "method": "POST",
    "path": "/notifications/ack",
    "description": "Acknowledge one or more notifications; removes them from the pending queue",
    "auth": "none",
    "actors": [
      "agent",
      "developer",
      "ci"
    ],
    "params": [
      {
        "name": "token",
        "kind": "string",
        "constraint": "required",
        "description": "Actor bearer token"
      },
      {
        "name": "ids",
        "kind": "string",
        "constraint": "required",
        "description": "Comma-separated notification ids to acknowledge"
      }
    ],
    "tags": [
      "notifications"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/notifications/pending",
    "description": "Poll pending notifications for an actor; optionally marks them as seen",
    "auth": "none",
    "actors": [
      "agent",
      "developer",
      "ci"
    ],
    "params": [
      {
        "name": "token",
        "kind": "string",
        "constraint": "required",
        "description": "Actor bearer token"
      },
      {
        "name": "project",
        "kind": "string",
        "constraint": "optional",
        "description": "Project slug filter"
      },
      {
        "name": "check_only",
        "kind": "bool",
        "constraint": "default=false",
        "description": "Return count without marking seen"
      }
    ],
    "tags": [
      "notifications"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/notifications/stream",
    "description": "SSE push stream: actor subscribes once and receives notification events as they occur",
    "auth": "none",
    "actors": [
      "agent",
      "developer"
    ],
    "params": [
      {
        "name": "token",
        "kind": "string",
        "constraint": "required",
        "description": "Actor bearer token"
      },
      {
        "name": "project",
        "kind": "string",
        "constraint": "optional",
        "description": "Project slug filter"
      }
    ],
    "tags": [
      "notifications",
      "sse"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/ontology",
    "description": "List available ontology extension files beyond core, state, gate, manifest",
    "auth": "none",
    "actors": [
      "agent",
      "developer"
    ],
    "params": [
      {
        "name": "slug",
        "kind": "string",
        "constraint": "optional",
        "description": "Project slug (defaults to primary)"
      }
    ],
    "tags": [
      "ontology"
    ],
    "feature": ""
  },
  {
    "method": "POST",
    "path": "/ontology/changed",
    "description": "Git hook endpoint: actor signs a file-change event it caused to suppress self-notification",
    "auth": "viewer",
    "actors": [
      "developer",
      "ci"
    ],
    "params": [
      {
        "name": "token",
        "kind": "string",
        "constraint": "required",
        "description": "Actor bearer token"
      },
      {
        "name": "files",
        "kind": "string",
        "constraint": "required",
        "description": "JSON array of changed file paths"
      }
    ],
    "tags": [
      "ontology",
      "notifications"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/ontology/{file}",
    "description": "Export a specific ontology extension file to JSON",
    "auth": "none",
    "actors": [
      "agent",
      "developer"
    ],
    "params": [
      {
        "name": "slug",
        "kind": "string",
        "constraint": "optional",
        "description": "Project slug (defaults to primary)"
      }
    ],
    "tags": [
      "ontology"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/projects",
    "description": "List all registered projects with slug, root, push_only flag and import path",
    "auth": "admin",
    "actors": [
      "admin"
    ],
    "params": [],
    "tags": [
      "projects",
      "registry"
    ],
    "feature": ""
  },
  {
    "method": "POST",
    "path": "/projects",
    "description": "Register a new project at runtime without daemon restart",
    "auth": "admin",
    "actors": [
      "admin"
    ],
    "params": [],
    "tags": [
      "projects",
      "registry"
    ],
    "feature": ""
  },
  {
    "method": "DELETE",
    "path": "/projects/{slug}",
    "description": "Deregister a project and stop its file watcher",
    "auth": "admin",
    "actors": [
      "admin"
    ],
    "params": [],
    "tags": [
      "projects",
      "registry"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/projects/{slug}/config",
    "description": "Full config export for a registered project (merged with any active overrides)",
    "auth": "none",
    "actors": [
      "agent",
      "developer"
    ],
    "params": [
      {
        "name": "slug",
        "kind": "string",
        "constraint": "required",
        "description": "Project slug"
      }
    ],
    "tags": [
      "config"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/projects/{slug}/config/coherence",
    "description": "Multi-consumer coherence report: unclaimed NCL fields, consumer field mismatches",
    "auth": "none",
    "actors": [
      "agent",
      "developer"
    ],
    "params": [
      {
        "name": "slug",
        "kind": "string",
        "constraint": "required",
        "description": "Project slug"
      },
      {
        "name": "section",
        "kind": "string",
        "constraint": "optional",
        "description": "Filter to one section"
      }
    ],
    "tags": [
      "config"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/projects/{slug}/config/quickref",
    "description": "Generated config documentation with rationales, override history, and coherence status",
    "auth": "none",
    "actors": [
      "agent",
      "developer"
    ],
    "params": [
      {
        "name": "slug",
        "kind": "string",
        "constraint": "required",
        "description": "Project slug"
      },
      {
        "name": "section",
        "kind": "string",
        "constraint": "optional",
        "description": "Filter to one section"
      },
      {
        "name": "format",
        "kind": "string",
        "constraint": "optional",
        "description": "Output format (json|markdown)"
      }
    ],
    "tags": [
      "config"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/projects/{slug}/config/schema",
    "description": "Config surface schema: sections with descriptions, rationales, contracts, and declared consumers",
    "auth": "none",
    "actors": [
      "agent",
      "developer"
    ],
    "params": [
      {
        "name": "slug",
        "kind": "string",
        "constraint": "required",
        "description": "Project slug"
      }
    ],
    "tags": [
      "config"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/projects/{slug}/config/{section}",
    "description": "Values for a single config section (from the merged NCL export)",
    "auth": "none",
    "actors": [
      "agent",
      "developer"
    ],
    "params": [
      {
        "name": "slug",
        "kind": "string",
        "constraint": "required",
        "description": "Project slug"
      },
      {
        "name": "section",
        "kind": "string",
        "constraint": "required",
        "description": "Section id"
      }
    ],
    "tags": [
      "config"
    ],
    "feature": ""
  },
  {
    "method": "PUT",
    "path": "/projects/{slug}/config/{section}",
    "description": "Mutate a config section via the override layer. dry_run=true (default) returns the proposed change without writing.",
    "auth": "admin",
    "actors": [
      "agent",
      "developer"
    ],
    "params": [
      {
        "name": "slug",
        "kind": "string",
        "constraint": "required",
        "description": "Project slug"
      },
      {
        "name": "section",
        "kind": "string",
        "constraint": "required",
        "description": "Section id"
      }
    ],
    "tags": [
      "config"
    ],
    "feature": ""
  },
  {
    "method": "PUT",
    "path": "/projects/{slug}/keys",
    "description": "Hot-rotate credentials for a project; invalidates all existing actor and UI sessions",
    "auth": "admin",
    "actors": [
      "admin"
    ],
    "params": [],
    "tags": [
      "projects",
      "auth"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/projects/{slug}/ontology/versions",
    "description": "Per-file ontology change counters for a project; incremented on every cache invalidation",
    "auth": "none",
    "actors": [
      "agent",
      "developer"
    ],
    "params": [],
    "tags": [
      "projects",
      "ontology",
      "cache"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/qa-json",
    "description": "Export the Q&A knowledge store as structured JSON from reflection/qa.ncl",
    "auth": "none",
    "actors": [
      "agent",
      "developer"
    ],
    "params": [
      {
        "name": "slug",
        "kind": "string",
        "constraint": "optional",
        "description": "Project slug (defaults to primary)"
      }
    ],
    "tags": [
      "qa"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/search",
    "description": "Full-text search over ontology nodes, ADRs, practices and Q&A entries",
    "auth": "none",
    "actors": [
      "agent",
      "developer"
    ],
    "params": [
      {
        "name": "q",
        "kind": "string",
        "constraint": "required",
        "description": "Search query string"
      },
      {
        "name": "slug",
        "kind": "string",
        "constraint": "optional",
        "description": "Project slug (ui feature only)"
      }
    ],
    "tags": [
      "search"
    ],
    "feature": ""
  },
  {
    "method": "POST",
    "path": "/sync",
    "description": "Push-based sync: remote projects POST their NCL export JSON here to update the daemon cache",
    "auth": "viewer",
    "actors": [
      "ci",
      "agent"
    ],
    "params": [
      {
        "name": "slug",
        "kind": "string",
        "constraint": "required",
        "description": "Project slug from Authorization header context"
      }
    ],
    "tags": [
      "sync",
      "federation"
    ],
    "feature": ""
  },
  {
    "method": "GET",
    "path": "/validate/adrs",
    "description": "Execute typed ADR constraint checks and return per-constraint pass/fail results",
    "auth": "viewer",
    "actors": [
      "developer",
      "ci",
      "agent"
    ],
    "params": [
      {
        "name": "slug",
        "kind": "string",
        "constraint": "optional",
        "description": "Project slug (defaults to primary)"
      }
    ],
    "tags": [
      "validate",
      "adrs"
    ],
    "feature": ""
  }
]
