Merge public-gh/master into PAP-989-multi-user-implementation-using-plan-from-pap-958

Co-Authored-By: Paperclip <noreply@paperclip.ing>

* public-gh/master:
  release: v2026.416.0 notes (#3782)
  Sync/master post pap1497 followups 2026 04 15 (#3779)
  [codex] improve issue and routine UI responsiveness (#3744)
  fix: disable HTTP caching on run log endpoints (#3724)
  [codex] harden heartbeat run summaries and recovery context (#3742)
  [codex] fix worktree dev dependency ergonomics (#3743)
  chore(ui): drop console.* and legal comments in production builds (#3728)
  fix: proper cache headers for static assets and SPA fallback (#3734)
  fix(a11y): remove maximum-scale and user-scalable=no from viewport (#3726)
  fix: trust PAPERCLIP_PUBLIC_URL in board mutation guard (#3731)
  [codex] harden authenticated routes and issue editor reliability (#3741)
  feat(adapters): add capability flags to ServerAdapterModule (#3540)
  fix: Anthropic subscription quota always shows 100% used (#3589)
  fix(server): respect externally set PAPERCLIP_API_URL env var (#3472)
  fix(routines): include cronExpression and timezone in list trigger response (#3209)
  fix: include routine-execution issues in agent inbox-lite (#3329)

# Conflicts:
#	server/src/__tests__/issues-service.test.ts
#	server/src/routes/access.ts
#	server/src/routes/plugins.ts
#	ui/src/components/IssueChatThread.tsx
#	ui/src/pages/Inbox.tsx

docs/adapters/creating-an-adapter.md

@@ -203,6 +203,43 @@ export const sessionCodec: AdapterSessionCodec = {
 };
 ```
 
+## Capability Flags
+
+Adapters can declare what "local" capabilities they support by setting optional fields on the `ServerAdapterModule`. The server and UI use these flags to decide which features to enable for agents using the adapter (instructions bundle editor, skills sync, JWT auth, etc.).
+
+| Flag | Type | Default | What it controls |
+|------|------|---------|------------------|
+| `supportsLocalAgentJwt` | `boolean` | `false` | Whether heartbeat generates a local JWT for the agent |
+| `supportsInstructionsBundle` | `boolean` | `false` | Managed instructions bundle (AGENTS.md) — server-side resolution + UI editor |
+| `instructionsPathKey` | `string` | `"instructionsFilePath"` | The `adapterConfig` key that holds the instructions file path |
+| `requiresMaterializedRuntimeSkills` | `boolean` | `false` | Whether runtime skill entries must be written to disk before execution |
+
+These flags are exposed via `GET /api/adapters` in a `capabilities` object, along with a derived `supportsSkills` flag (true when `listSkills` or `syncSkills` is defined).
+
+### Example
+
+```ts
+export function createServerAdapter(): ServerAdapterModule {
+  return {
+    type: "my_k8s_adapter",
+    execute: myExecute,
+    testEnvironment: myTestEnvironment,
+    listSkills: myListSkills,
+    syncSkills: mySyncSkills,
+
+    // Capability flags
+    supportsLocalAgentJwt: true,
+    supportsInstructionsBundle: true,
+    instructionsPathKey: "instructionsFilePath",
+    requiresMaterializedRuntimeSkills: true,
+  };
+}
+```
+
+With these flags set, the Paperclip UI will automatically show the instructions bundle editor, skills management tab, and working directory field for agents using this adapter — no Paperclip source changes required.
+
+If capability flags are not set, the server falls back to legacy hardcoded lists for built-in adapter types. External adapters that omit the flags will default to `false` for all capabilities.
+
 ## Skills Injection
 
 Make Paperclip skills discoverable to your agent runtime without writing to the agent's working directory:

docs/deploy/environment-variables.md

@@ -18,6 +18,7 @@ All environment variables that Paperclip uses for server configuration.
 | `PAPERCLIP_INSTANCE_ID` | `default` | Instance identifier (for multiple local instances) |
 | `PAPERCLIP_DEPLOYMENT_MODE` | `local_trusted` | Runtime mode override |
 | `PAPERCLIP_DEPLOYMENT_EXPOSURE` | `private` | Exposure policy when deployment mode is `authenticated` |
+| `PAPERCLIP_API_URL` | (auto-derived) | Paperclip API base URL. When set externally (e.g., via Kubernetes ConfigMap, load balancer, or reverse proxy), the server preserves the value instead of deriving it from the listen host and port. Useful for deployments where the public-facing URL differs from the local bind address. |
 
 ## Secrets
 
@@ -35,7 +36,7 @@ These are set automatically by the server when invoking agents:
 |----------|-------------|
 | `PAPERCLIP_AGENT_ID` | Agent's unique ID |
 | `PAPERCLIP_COMPANY_ID` | Company ID |
-| `PAPERCLIP_API_URL` | Paperclip API base URL |
+| `PAPERCLIP_API_URL` | Paperclip API base URL (inherits the server-level value; see Server Configuration above) |
 | `PAPERCLIP_API_KEY` | Short-lived JWT for API auth |
 | `PAPERCLIP_RUN_ID` | Current heartbeat run ID |
 | `PAPERCLIP_TASK_ID` | Issue that triggered this wake |