natureco-cli 5.18.2 → 5.19.0

package/skills/nodejs-core/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: nodejs-core
+description: Debugs native module crashes, optimizes V8 performance, configures node-gyp builds, writes N-API/node-addon-api bindings, and diagnoses libuv event loop issues in Node.js. Use when working with C++ addons, native modules, binding.gyp, node-gyp errors, segfaults, memory leaks in native code, V8 optimization/deoptimization, libuv thread pool tuning, N-API or NAN bindings, build system failures, or any Node.js internals below the JavaScript layer.
+metadata:
+  tags: nodejs, v8, libuv, cpp, native-addons, performance, debugging, internals
+---
+
+## When to use
+
+Use this skill when you need deep Node.js internals expertise, including:
+- C++ addon development
+- V8 engine debugging
+- libuv event loop issues
+- Build system problems
+- Compilation failures
+- Performance optimization at the engine level
+- Understanding Node.js core architecture
+
+## How to use
+
+Read individual rule files for detailed explanations and code examples:
+
+### V8 Engine
+
+- [rules/v8-garbage-collection.md](rules/v8-garbage-collection.md) - Scavenger, Mark-Sweep, Mark-Compact, generational GC
+- [rules/v8-hidden-classes.md](rules/v8-hidden-classes.md) - Hidden classes, inline caching, optimization
+- [rules/v8-jit-compilation.md](rules/v8-jit-compilation.md) - TurboFan, optimization/deoptimization patterns
+
+### libuv
+
+- [rules/libuv-event-loop.md](rules/libuv-event-loop.md) - Event loop phases, timers, I/O, idle, check, close
+- [rules/libuv-thread-pool.md](rules/libuv-thread-pool.md) - Thread pool size, blocking operations, UV_THREADPOOL_SIZE
+- [rules/libuv-async-io.md](rules/libuv-async-io.md) - Async I/O patterns, handles, requests
+
+### Native Addons
+
+- [rules/napi.md](rules/napi.md) - N-API development, ABI stability, async workers
+- [rules/node-addon-api.md](rules/node-addon-api.md) - C++ wrapper patterns, best practices
+- [rules/native-memory.md](rules/native-memory.md) - Buffer handling, external memory, prevent leaks
+
+### Core Modules Internals
+
+- [rules/streams-internals.md](rules/streams-internals.md) - How Node.js streams work at C++ level
+- [rules/net-internals.md](rules/net-internals.md) - TCP/UDP implementation, socket handling
+- [rules/fs-internals.md](rules/fs-internals.md) - libuv fs operations, sync vs async
+- [rules/crypto-internals.md](rules/crypto-internals.md) - OpenSSL integration, performance considerations
+- [rules/child-process-internals.md](rules/child-process-internals.md) - IPC, spawn, fork implementation
+- [rules/worker-threads-internals.md](rules/worker-threads-internals.md) - SharedArrayBuffer, Atomics, MessageChannel
+
+### JavaScript Internals
+
+- [rules/primordials.md](rules/primordials.md) - **Using primordials to prevent prototype pollution (required for `lib/internal/`)**
+
+### Build & Contributing
+
+- [rules/build-and-test-workflow.md](rules/build-and-test-workflow.md) - **The edit-build-lint-test cycle (start here)**
+- [rules/configure.md](rules/configure.md) - `./configure` flags for debug builds, ASan, Ninja, etc.
+- [rules/build-system.md](rules/build-system.md) - gyp, ninja, make, cross-platform compilation
+- [rules/cli-options.md](rules/cli-options.md) - Adding CLI options and gating experimental modules
+- [rules/contributing.md](rules/contributing.md) - How to contribute to Node.js core, the process
+- [rules/commit-messages.md](rules/commit-messages.md) - Node.js-style commit message formatting and validation
+- [rules/reviewing-prs.md](rules/reviewing-prs.md) - Reviewing PRs, quality signals, and spotting low-quality AI-generated contributions
+
+### Documentation
+
+- [rules/documentation.md](rules/documentation.md) - **Updating doc/api/*.md files: structure, link ordering, error docs, code example constraints**
+
+### Debugging & Profiling
+
+- [rules/debugging-native.md](rules/debugging-native.md) - gdb, lldb, debugging C++ addons
+- [rules/profiling-v8.md](rules/profiling-v8.md) - --prof, --trace-opt, --trace-deopt, flame graphs
+- [rules/memory-debugging.md](rules/memory-debugging.md) - Heap snapshots, memory leak detection
+
+## Instructions
+
+### MANDATORY: Rebuild before testing
+
+Node.js embeds `lib/` JavaScript files into the binary at compile time via
+`js2c`. **After ANY change to `src/` or `lib/`, you MUST rebuild before
+running tests.** Without a rebuild, tests run against stale code and results
+are meaningless.
+
+```
+edit src/ or lib/  →  make -j$(nproc)  →  make lint  →  then test
+```
+
+Never skip the rebuild step. Never run `./node test/...` after editing
+without building first.
+
+Before starting work, **ask the user** about their build configuration
+(Make vs Ninja, debug vs release, what configure flags they use). Do not
+assume a specific setup. Most of the time, `./configure` has already been
+run and only `make -j$(nproc)` is needed to rebuild.
+
+See [rules/build-and-test-workflow.md](rules/build-and-test-workflow.md)
+for the full workflow including configure flags, lint targets, and test
+commands.
+
+### Core knowledge domains
+
+Apply deep knowledge of Node.js internals across these domains:
+
+- **Core architecture**: Node.js core modules and their C++ implementations, V8 GC and JIT, libuv event loop mechanics, thread pool behavior, startup/module-loading lifecycle
+- **Native development**: N-API, node-addon-api, and NAN addon development; V8 C++ API handle management; memory safety; native debugging with gdb/lldb
+- **Build systems**: node-gyp, gyp, ninja, make; cross-platform compilation; linker errors; dependency issues; platform-specific considerations (Windows, macOS, Linux, embedded)
+- **Performance & debugging**: Event loop profiling, memory leak detection in JS and native code, CPU flame graphs, V8 optimization/deoptimization tracing
+
+### Quick-reference debugging commands
+
+**V8 optimization tracing:**
+```bash
+node --trace-opt --trace-deopt script.js
+# Checkpoint: confirm no unexpected deoptimization warnings before proceeding to profiling
+node --prof script.js && node --prof-process isolate-*.log > processed.txt
+```
+
+**Event loop lag detection:**
+```bash
+node --trace-event-categories v8,node,node.async_hooks script.js
+```
+
+**Native addon debugging (gdb):**
+```bash
+gdb --args node --napi-modules ./build/Release/addon.node
+# Inside gdb:
+run
+bt        # backtrace on crash
+# Checkpoint: verify backtrace shows the expected call site before applying a fix
+```
+
+**Heap snapshot for memory leaks:**
+```bash
+node --inspect script.js   # then open chrome://inspect, take heap snapshot
+# Checkpoint: compare two consecutive heap snapshots to confirm leak growth before and after the fix; run valgrind --leak-check=full node addon_test.js to confirm no native leaks remain
+```
+
+### Node.js-specific diagnostic decision trees
+
+**Segfault / crash in native addon:**
+1. Is the crash reproducible with `node --napi-modules`? → Run `gdb`, capture `bt`
+2. Does `bt` point to a V8 handle scope issue? → Check `HandleScope` / `EscapableHandleScope` usage in the addon
+3. Does it point to a libuv callback? → Inspect async handle lifetime and `uv_close()` sequencing
+4. No clear C++ frame? → Check for JS-side type mismatches passed into the native binding
+
+**V8 deoptimization / performance regression:**
+1. Run `--trace-opt --trace-deopt` → identify the deoptimized function and reason (e.g., "not a Smi", "wrong map")
+2. Checkpoint: confirm the same function deoptimizes consistently across runs
+3. Inspect hidden class transitions (`--trace-ic`) and fix property addition order or type inconsistencies
+4. Re-run `--trace-opt` to confirm the function is now optimized
+
+**Build failure (node-gyp / binding.gyp):**
+1. Is it a missing header? → Verify `include_dirs` in `binding.gyp` and Node.js header installation
+2. Is it a linker error? → Check `libraries` and `link_settings` entries; confirm ABI compatibility
+3. Is it platform-specific? → Consult `rules/build-system.md` for Windows/macOS/Linux differences
+
+Always consider both JavaScript-level and native-level causes, explain performance implications and trade-offs, and indicate the stability status of any experimental features discussed. Code examples should demonstrate Node.js internals patterns and be production-ready, accounting for edge cases typical developers might miss.

package/skills/oauth/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: oauth
+description: Implements OAuth 2.0/2.1 authorization flows in Fastify applications — configures authorization code with PKCE, client credentials, device flow, refresh token rotation, JWT validation, and token introspection/revocation endpoints. Use when setting up authentication, authorization, login flows, access tokens, API security, or securing Fastify routes with OAuth; also applies when troubleshooting token validation errors, mismatched redirect URIs, CSRF issues, scope problems, or RFC 6749/6750/7636/8252/8628 compliance questions.
+metadata:
+  tags: oauth, oauth2, security, authentication, authorization, jwt, fastify
+---
+
+## When to use
+
+Use this skill when you need to:
+- Implement or debug an OAuth 2.0/2.1 flow in a Fastify application
+- Validate tokens, configure PKCE, or set up refresh token rotation
+- Secure Fastify routes and plugins with access-control middleware
+- Resolve RFC compliance questions or identify security anti-patterns
+
+---
+
+## Step-by-step: Authorization Code + PKCE in Fastify
+
+### 1. Install dependencies
+
+```bash
+npm install @fastify/oauth2 @fastify/cookie @fastify/session fastify-plugin
+```
+
+### 2. Register the OAuth plugin
+
+```typescript
+// plugins/oauth.ts
+import fp from 'fastify-plugin'
+import oauth2, { OAuth2Namespace } from '@fastify/oauth2'
+import { FastifyInstance } from 'fastify'
+
+export default fp(async function (fastify: FastifyInstance) {
+  fastify.register(oauth2, {
+    name: 'oauth2',
+    scope: ['openid', 'profile', 'email'],
+    credentials: {
+      client: {
+        id: process.env.CLIENT_ID!,
+        secret: process.env.CLIENT_SECRET!,
+      },
+      auth: {
+        authorizeHost: process.env.AUTH_SERVER!,
+        authorizePath: '/authorize',
+        tokenHost: process.env.AUTH_SERVER!,
+        tokenPath: '/token',
+      },
+    },
+    startRedirectPath: '/login',
+    callbackUri: process.env.CALLBACK_URI!,
+    pkce: 'S256',               // RFC 7636 — always use for public clients
+    generateStateFunction: (req) => req.session.state = crypto.randomUUID(),
+    checkStateFunction: (req, callback) =>
+      req.query.state === req.session.state ? callback() : callback(new Error('State mismatch')),
+  })
+})
+```
+
+**Validation checkpoint:** Confirm `callbackUri` exactly matches a registered redirect URI at the authorization server before proceeding (RFC 6749 §3.1.2).
+
+### 3. Handle the callback and exchange the code
+
+```typescript
+// routes/auth.ts
+import { FastifyInstance } from 'fastify'
+
+export default async function authRoutes(fastify: FastifyInstance) {
+  fastify.get('/login/callback', async (request, reply) => {
+    // @fastify/oauth2 verifies state and exchanges code automatically
+    const tokenResponse = await fastify.oauth2.getAccessTokenFromAuthorizationCodeFlow(request)
+
+    // Store only what you need; never log the raw token
+    request.session.set('accessToken', tokenResponse.token.access_token)
+    request.session.set('refreshToken', tokenResponse.token.refresh_token)
+
+    return reply.redirect('/')
+  })
+
+  fastify.get('/logout', async (request, reply) => {
+    await request.session.destroy()
+    return reply.redirect('/')
+  })
+}
+```
+
+### 4. JWT validation middleware (token introspection hook)
+
+```typescript
+// hooks/verifyToken.ts
+import { FastifyRequest, FastifyReply } from 'fastify'
+import jwt from '@fastify/jwt'
+
+export async function verifyToken(request: FastifyRequest, reply: FastifyReply) {
+  try {
+    await request.jwtVerify()
+    // Validate required claims (RFC 7519)
+    const payload = request.user as Record<string, unknown>
+    const now = Math.floor(Date.now() / 1000)
+
+    if (typeof payload.exp === 'number' && payload.exp < now)
+      return reply.code(401).send({ error: 'token_expired' })
+
+    if (payload.iss !== process.env.EXPECTED_ISSUER)
+      return reply.code(401).send({ error: 'invalid_issuer' })
+
+    if (payload.aud !== process.env.EXPECTED_AUDIENCE)
+      return reply.code(401).send({ error: 'invalid_audience' })
+
+  } catch (err) {
+    return reply.code(401).send({ error: 'invalid_token', error_description: (err as Error).message })
+  }
+}
+```
+
+**Validation checkpoints:**
+- Verify `exp`, `iss`, `aud`, and `sub` on every request — never skip (RFC 7519 §4)
+- Use `fastify.jwt.verify` (asymmetric RS256/ES256) rather than HS256 for tokens issued by a third-party server
+
+### 5. Protecting routes
+
+```typescript
+// routes/api.ts
+import { FastifyInstance } from 'fastify'
+import { verifyToken } from '../hooks/verifyToken'
+
+export default async function apiRoutes(fastify: FastifyInstance) {
+  fastify.addHook('onRequest', verifyToken)   // applies to all routes in this scope
+
+  fastify.get('/me', {
+    schema: {
+      response: { 200: { type: 'object', properties: { sub: { type: 'string' } } } },
+    },
+  }, async (request) => {
+    const user = request.user as { sub: string }
+    return { sub: user.sub }
+  })
+}
+```
+
+### 6. Refresh token rotation
+
+```typescript
+async function refreshAccessToken(fastify: FastifyInstance, refreshToken: string) {
+  const newToken = await fastify.oauth2.getNewAccessTokenUsingRefreshTokenFlow({ refresh_token: refreshToken })
+
+  // Always replace the stored refresh token if rotation is in use (RFC 6749 §10.4)
+  return {
+    accessToken: newToken.token.access_token,
+    refreshToken: newToken.token.refresh_token ?? refreshToken,
+  }
+}
+```
+
+---
+
+## Security checklist
+
+| Requirement | RFC reference |
+|---|---|
+| Validate redirect URI against allowlist | RFC 6749 §3.1.2 |
+| PKCE (S256) for all public clients | RFC 7636 §4.2 |
+| Validate `state` to prevent CSRF | RFC 6749 §10.12 |
+| Validate `iss`, `aud`, `exp` on every JWT | RFC 7519 §4 |
+| Rotate refresh tokens on every use | RFC 6749 §10.4 |
+| Use HTTPS everywhere; reject HTTP redirect URIs | RFC 6749 §3.1.2.1 |
+| Rate-limit token endpoints | OAuth 2.1 §7 |
+
+---
+
+## Common anti-patterns
+
+- **Storing tokens in localStorage** — use `HttpOnly`, `Secure`, `SameSite=Strict` cookies instead
+- **Skipping audience validation** — allows token reuse across services
+- **Using implicit flow** — deprecated in OAuth 2.1; use authorization code + PKCE
+- **Accepting `response_type=token` in browser apps** — tokens in URL fragments leak in logs/referrers
+- **Symmetric signing (HS256) for third-party tokens** — use RS256/ES256 with JWKS endpoint
+
+---
+
+## Further implementation references
+
+- See `DEVICE_FLOW.md` for device authorization flow (RFC 8628) implementation
+- See `TOKEN_VALIDATION.md` for JWKS rotation, caching strategies, and opaque token introspection
+- See `CLIENT_CREDENTIALS.md` for machine-to-machine service authentication patterns
+- See `MOBILE_OAUTH.md` for native/mobile app flows (RFC 8252) and custom URI schemes

package/skills/obsidian-vault/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: obsidian-vault
+description: Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. Use when user wants to find, create, or organize notes in Obsidian.
+---
+
+# Obsidian Vault
+
+## Vault location
+
+`/mnt/d/Obsidian Vault/AI Research/`
+
+Mostly flat at root level.
+
+## Naming conventions
+
+- **Index notes**: aggregate related topics (e.g., `Ralph Wiggum Index.md`, `Skills Index.md`, `RAG Index.md`)
+- **Title case** for all note names
+- No folders for organization - use links and index notes instead
+
+## Linking
+
+- Use Obsidian `[[wikilinks]]` syntax: `[[Note Title]]`
+- Notes link to dependencies/related notes at the bottom
+- Index notes are just lists of `[[wikilinks]]`
+
+## Workflows
+
+### Search for notes
+
+```bash
+# Search by filename
+find "/mnt/d/Obsidian Vault/AI Research/" -name "*.md" | grep -i "keyword"
+
+# Search by content
+grep -rl "keyword" "/mnt/d/Obsidian Vault/AI Research/" --include="*.md"
+```
+
+Or use Grep/Glob tools directly on the vault path.
+
+### Create a new note
+
+1. Use **Title Case** for filename
+2. Write content as a unit of learning (per vault rules)
+3. Add `[[wikilinks]]` to related notes at the bottom
+4. If part of a numbered sequence, use the hierarchical numbering scheme
+
+### Find related notes
+
+Search for `[[Note Title]]` across the vault to find backlinks:
+
+```bash
+grep -rl "\\[\\[Note Title\\]\\]" "/mnt/d/Obsidian Vault/AI Research/"
+```
+
+### Find index notes
+
+```bash
+find "/mnt/d/Obsidian Vault/AI Research/" -name "*Index*"
+```

package/skills/octocat/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: octocat
+description: Use this skill whenever the prompt contains any `github.com` URL, even if the user only pastes a link and gives no GitHub-specific keywords. Handles git and GitHub operations using the gh CLI. Triggers include any GitHub link to an issue, pull request, commit, compare page, Actions run, release, discussion, or repository. Covers creating and reviewing PRs, watching CI checks, interactive rebasing, branch cleanup, submodule management, and repository archaeology with git log/blame/bisect.
+metadata:
+  tags: git, github, gh-cli, version-control, merge-conflicts, pull-requests
+---
+
+## When to use
+
+Use this skill for:
+- Any prompt containing a pasted `github.com` URL, even without words like "GitHub", "issue", "PR", or "repo"
+- Any GitHub link to an issue, pull request, commit, compare page, Actions run, release, discussion, or repository
+- "Fix https://github.com/owner/repo/issues/123" style tasks
+- Creating, reviewing, and managing pull requests and GitHub issues
+- Merge conflict resolution and history rewriting
+- Pre-commit hook debugging and fixes
+- Branch management and cleanup
+- GitHub Actions workflow optimization
+- Any git command or GitHub workflow question
+
+## Instructions
+
+When invoked:
+1. If the prompt includes a GitHub URL, treat that URL alone as sufficient reason to invoke this skill and inspect it with `gh`/`git` first
+2. Assess the git/GitHub situation immediately
+3. If the prompt includes a `github.com` URL, activate this skill immediately and translate that URL into the relevant `gh`/`git` workflow
+4. Use gh CLI for all GitHub operations (never suggest the web interface)
+5. Handle complex git operations with surgical precision
+6. Fix pre-commit hook issues or delegate to typescript-magician for TypeScript linting
+7. Never alter git signing key configuration; if signing is already enabled and configured, use it. Otherwise, proceed without signing
+8. NEVER include "Co-Authored-By: Claude" or similar AI attribution
+
+## Activation examples
+
+- `Fix https://github.com/mercurius-js/mercurius/issues/1227`
+- `Review https://github.com/nodejs/node/pull/12345`
+- `What changed in https://github.com/org/repo/compare/v1.0.0...v1.1.0?`
+- `Check https://github.com/org/repo/actions/runs/123456789`
+- `Investigate https://github.com/org/repo/commit/abcdef1234567890`
+
+## Capabilities
+
+**Advanced git operations:**
+- Interactive rebasing for clean history (commit splitting, squashing)
+- Cherry-pick, bisect, worktrees
+- Advanced merge strategies
+- Submodule and subtree management
+- Git hooks setup and maintenance
+- Repository archaeology with git log/blame/show
+
+**GitHub operations via gh CLI:**
+- Create/manage PRs with proper templates
+- Open PRs with explicit base/head and clear concise content, e.g. `gh pr create --base main --head <branch> --title "<title>" --body-file <file>`
+- After opening a PR, wait for CI with `gh pr checks <num> --watch 2>&1` and proactively fix failures
+- Validate unfamiliar gh commands first with `gh help <command>` before using them in guidance
+- Handle issues and project boards
+- Manage releases and artifacts
+- Configure repository settings
+- Automate workflows and notifications
+
+## PR Body Formatting
+
+When creating PRs with `gh pr create`, use `--body-file` to avoid newline escaping issues with the `--body` flag.
+
+PR descriptions should stay simple:
+- Write a short description of the change in plain prose
+- Do not add subsections or headings such as `## Summary` or `## Testing`
+- Do not include a testing section
+- Architecture changes may need a slightly longer description if extra context is necessary
+
+```bash
+cat > /tmp/pr-body.md << 'EOF'
+Refactor plugin loading so skills are discovered from the registry instead of being hardcoded.
+EOF
+gh pr create --body-file /tmp/pr-body.md
+```
+
+Using a temporary file is cleaner, more reliable, and easier to debug.
+
+## Validation Checkpoints for Complex Operations
+
+**Interactive rebase:** `git rebase -i <base>` → verify with `git log --oneline -n 10` → on conflict: resolve, `git add <file>`, `git rebase --continue` → abort anytime with `git rebase --abort`.
+
+**Merge conflict resolution:** `git status` (find conflicts) → inspect with `git diff` or open file → resolve all markers → `git add <resolved-file>` → `git merge --continue` (or `git rebase --continue`) → confirm clean state with `git status`.
+
+**Branch cleanup:** `git branch --merged main` → `git branch -d <branch>` → `git push origin --delete <branch>` → `git fetch --prune`.
+
+## Commit Signing and Attribution Rules
+
+- NEVER alter git signing key settings (`user.signingkey`) or signing mode in user/repo config
+- If commit signing is already enabled and correctly configured, create signed commits using the existing setup
+- If signing is not enabled/configured, do not force or configure signing; proceed without it
+- NEVER add AI co-authorship attributions (e.g. "Co-Authored-By: Claude")

package/skills/openclaw-secure-linux-cloud/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: openclaw-secure-linux-cloud
+description: Use when self-hosting OpenClaw on a cloud server, hardening a remote OpenClaw gateway, choosing between SSH tunneling, Tailscale, or reverse-proxy exposure, or reviewing Podman, pairing, sandboxing, token auth, and tool-permission defaults for a secure personal deployment.
+---
+
+## Overview
+
+Use this skill for the conservative "deploy first, expose later" pattern for
+OpenClaw on a cloud server.
+
+Default to a private control plane:
+
+- Harden the Linux host before exposing anything.
+- Keep the gateway bound to `127.0.0.1`.
+- Reach the Control UI through an SSH tunnel first.
+- Keep token authentication, pairing, and sandboxing enabled.
+- Start with a narrow tool profile and loosen only with an explicit need.
+
+This skill is for secure Linux cloud hosting. If the user only wants the
+fastest generic OpenClaw install on a local machine, prefer the official
+OpenClaw onboarding docs instead of forcing this flow.
+
+Open [`references/REFERENCE.md`](./references/REFERENCE.md) when you need the
+command matrix, baseline config shape, checklist, or access-path comparison.
+
+## When To Use
+
+Use this skill when the user mentions any of the following:
+
+- OpenClaw on a cloud server, VM, or other Linux host
+- Secure self-hosting, hardening, or "run it privately"
+- Podman, loopback binding, SSH tunneling, or remote Control UI access
+- Tailscale vs reverse proxy for OpenClaw
+- Pairing, sandboxing, token auth, or locked-down tool permissions
+- Reviewing whether an existing OpenClaw host is too exposed
+
+Do not use this skill for:
+
+- General Linux hardening with no OpenClaw component
+- Local single-machine onboarding where remote access is irrelevant
+- Pure local onboarding with no remote-host hardening questions
+- Non-Linux hosting unless the user explicitly wants this Linux-first pattern
+  adapted
+
+## Workflow
+
+### 1. Classify the request
+
+Put the task in one of these buckets before giving detailed guidance:
+
+1. **Fresh deploy**: the user wants to stand up OpenClaw securely on a Linux
+   cloud host from scratch.
+2. **Hardening review**: the user already has OpenClaw running and wants to
+   reduce exposure or audit risky defaults.
+3. **Access-model decision**: the user is choosing between SSH tunneling,
+   Tailscale, or a reverse proxy.
+
+### 2. Start from the secure baseline
+
+Unless the user clearly asks for something else, recommend this baseline:
+
+- Harden the Linux host first: updates, SSH keys, SSH lock-down, and a
+  default-deny inbound firewall matched to the distro.
+- Run OpenClaw under rootless Podman rather than as a root-owned long-lived
+  process.
+- Keep the gateway on loopback only.
+- Keep the Control UI private and access it through an SSH tunnel.
+- Require token authentication.
+- Keep pairing enabled for inbound messaging channels.
+- Start with a minimal tool set and sandbox sessions by default.
+
+Treat these as explicit red flags:
+
+- Binding the gateway to `0.0.0.0`
+- Opening port `18789` to the public internet
+- Turning on broad runtime, filesystem, automation, or browser access by
+  default
+- Leaving `~/.openclaw` readable by other local users
+
+### 3. Separate local and server actions
+
+Always distinguish between:
+
+- **Local machine actions**: SSH key generation, tunnel setup, browser access
+- **Server actions**: Linux hardening, Podman install path, OpenClaw service
+  setup, config permissions, service restarts
+
+Do not blur the two execution contexts together. The user should be able to
+tell which commands run on their laptop and which run on the Linux host.
+
+### 4. Ask only for blocking facts
+
+Only stop for missing facts that change the safe path, such as:
+
+- Linux distro and host access details when package-manager or firewall
+  commands matter
+- Whether OpenClaw is already installed
+- Whether the user truly needs repeated remote private access or public access
+- Whether an existing deployment is already reachable from the internet
+
+If a detail is not safety-critical, make the reasonable secure assumption and
+state it.
+
+### 5. Use the access escalation ladder
+
+Recommend remote access in this order:
+
+1. **SSH tunnel**: default for first deployment and personal use
+2. **Tailscale**: next step when the user needs repeated private access across
+   trusted devices
+3. **Reverse proxy**: only when the user explicitly needs public exposure and
+   accepts the extra hardening burden
+
+If the user asks for Tailscale or reverse proxy, still explain why the loopback
+binding and private-first model remain the baseline.
+
+## Output Expectations
+
+For a fresh deployment, provide:
+
+- A short architecture summary
+- Local-vs-server steps
+- A conservative config baseline
+- A pre-launch checklist
+- A short "what not to expose" warning
+
+For a hardening review, provide:
+
+- The likely risks in the current setup
+- A prioritized remediation sequence
+- Any immediate exposure concerns to fix before anything else
+
+For an access-path decision, provide:
+
+- A recommendation
+- Why it is the lowest-risk fit
+- What extra safeguards are required if the user chooses a broader exposure
+  model
+
+## Common Mistakes
+
+- Treating OpenClaw like a normal public web app on day one
+- Assuming auth alone replaces network boundaries
+- Turning on more tool power before the user has a clear workflow that needs it
+- Disabling pairing just to save time during early setup
+- Skipping follow-up audits after changing config or sandbox settings
+
+## Reference Usage
+
+Use [`references/REFERENCE.md`](./references/REFERENCE.md) when you need:
+
+- The cross-distro hardening flow and Debian/Ubuntu example commands
+- The Podman-based OpenClaw setup outline
+- The baseline config skeleton
+- The pre-launch checklist
+- The day-to-day audit commands
+- The SSH tunnel vs Tailscale vs reverse-proxy comparison