docs: add safety docs and OpenClaw gap roadmap

docs/api/TOOLS.md

@@ -54,6 +54,9 @@ export interface Tool {
   /** JSON Schema for input validation. */
   inputSchema: JSONSchema;
 
+  /** Secret scopes required to execute this tool (optional). */
+  requiredSecretScopes?: string[];
+
   /** Async function that executes the tool. */
   execute: (args: unknown) => Promise<ToolResult>;
 }
@@ -441,26 +444,14 @@ Tool policy controls which tools are available to agents based on profiles and p
 
 ### Profiles
 
-```typescript
-export const PROFILES = {
-  minimal: {
-    allow: ['system.info'],
-    deny: []
-  },
-  messaging: {
-    allow: ['system.info', 'memory.read', 'memory.write'],
-    deny: ['shell.*', 'file.*', 'process.*']
-  },
-  coding: {
-    allow: ['*'],
-    deny: ['group:runtime']
-  },
-  full: {
-    allow: ['*'],
-    deny: []
-  }
-};
-```
+Flynn ships 4 built-in profiles:
+
+- `minimal`: read-only (file read/list + web.fetch + system.info)
+- `messaging`: read-only + web search + memory + connected read APIs (gmail/gcal/gdocs/gdrive/gtasks)
+- `coding`: adds filesystem writes, shell/process, and browser automation
+- `full`: all registered tools
+
+The authoritative profile tool sets live in `src/tools/policy.ts`.
 
 ### Groups
 
@@ -471,39 +462,53 @@ Tools are organized into groups:
 - `group:web`: Web and browser tools
 - `group:memory`: Memory and search tools
 
+There are additional groups for specific integrations (gmail/gcal/gdocs/gdrive/gtasks/cron). See `TOOL_GROUPS` in `src/tools/policy.ts`.
+
 ### Policy Resolution
 
-When listing tools for an agent:
+When resolving tools for an execution context:
 
-1. Start with profile's allow list
-2. Remove tools in deny list
-3. Apply per-agent overrides
-4. Apply per-provider overrides
-5. Apply hook patterns (confirm/log/silent)
+1. Start with global `tools.profile`
+2. Apply global `tools.allow` (adds tools back in)
+3. Apply global `tools.deny` (deny always wins)
+4. If `context.agent` override exists, intersect with agent override resolution
+5. If `context.provider` override exists, intersect with provider override resolution
+6. If `context.skillName` is set, intersect with skill capability allowlist (deny-by-default for skills)
+
+Hooks/autonomy are enforced at execution-time (ToolExecutor), not during list resolution.
 
 ### Example Policy Config
 
 ```yaml
 tools:
-  policy: 'coding'  # Default profile
-
-  profiles:
-    coding:
-      allow: ['*']
-      deny: ['group:runtime']
+  profile: messaging
+  allow: []
+  deny: ["browser.*"]
 
   # Per-agent overrides
   agents:
-    my-agent:
-      toolPolicy: 'full'
+    fast:
+      profile: minimal
+      allow: []
+      deny: []
 
   # Per-provider overrides
   providers:
-    anthropic:
-      allow: ['*']
-      deny: []
+    ollama:
+      profile: messaging
+      allow: []
+      deny: ["web.search"]
 ```
 
+### Skill Capabilities (Skill Context)
+
+If a request is routed into a skill context (via intents), Flynn applies an additional restriction layer using the skill's `manifest.json.permissions`.
+
+- A skill with no `permissions` manifest has no tool access.
+- `permissions.tools` (explicit allowlist) overrides `permissions.tool_groups`.
+
+See `docs/security/SAFE_PERSONAL_AGENT.md`.
+
 ## Tool Execution Flow
 
 ### Execution Pipeline