docs: Add mintlify docs by gagdiez · Pull Request #2189 · nearai/ironclaw

gagdiez · 2026-04-09T09:51:08Z

Summary

So far we kept our user-facing documentation on a [separate repo](, this PR merges those docs (https://github.com/nearai/ironclaw-docs) into this mono-repo

Change Type

Linked Issue

Closes #1174 #2188

Validation

cargo fmt --all -- --check
cargo clippy --all --benches --tests --examples --all-features -- -D warnings
cargo build
Relevant tests pass:
cargo test --features integration if database-backed or integration behavior changed
Manual testing: mint dev
If a coding agent was used and supports it, review-pr or pr-shepherd --fix was run before requesting review

Security Impact

None

Database Impact

None

Blast Radius

None

Review Follow-Through

Moved existing telegram docs to /docs/channels/telegram, moved llm-providers to /docs/capabilities, left /docs/plans there, moved all other docs to /docs/internal (development-history, engine-v2-architecture, self-improvement, smart-routing-spec, user-managment-api)

Review track: A

Updated the README to reflect the new project name and removed references to the Mintlify Starter Kit.

feat: added more channels

feat: add Chinese (zh) internationalization for documentation

* feat: add comprehensive IronClaw documentation site - Full Mintlify docs site covering agents, channels, tools, security, install, and UI reference - Screenshot pipeline with Playwright tests for all major web UI pages - Architecture diagrams (Excalidraw + PNG/SVG) for security, secrets, sandbox, and system overview - Provider docs for Anthropic, OpenAI, Ollama, NearAI, Moonshot, and Tinfoil - Platform guides for Linux, macOS, Windows (native + WSL2), Raspberry Pi, VPS, and Docker - Operations reference for API, logging, orchestrator, and WebSocket/SSE - Help section with FAQ and troubleshooting Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat: add building a tool extension guide * chore: first round removing files * chore: slowly merging * migrated routines, memory, jobs, skills, and more * chore: remove files * chore: remove tests * feat: added new tools * chore: removed agents file as we have skills --------- Co-authored-by: Corey Osman <corey@logicminds.biz> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: Matias Benary <matiasbenary@gmail.com> Co-authored-by: Guillermo Alejandro Gallardo Diez <gagdiez@iR2.local>

Co-authored-by: Guillermo Alejandro Gallardo Diez <gagdiez@iR2.local>

* feat: add tutorials for Google APIs (Docs,Drive,Sheet,Slides) * feat: add tutorials for Gmail * chore: clean google sheets * chore: add zh translations --------- Co-authored-by: Matias Benary <matiasbenary@gmail.com> Co-authored-by: Guillermo Alejandro Gallardo Diez <gagdiez@iR2.local>

git-subtree-dir: docs git-subtree-mainline: 2bc6929 git-subtree-split: f60aeae

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR migrates user-facing documentation from the external ironclaw-docs repo into this monorepo and sets it up to be served via Mintlify.

Changes:

Adds a Mintlify docs.json navigation/config and supporting ignore files.
Introduces a large set of new docs pages (install, platforms, capabilities, channels, ops, agents) under docs/ (and docs/drafts/).
Updates README files and CONTRIBUTING to point contributors/users at the new docs structure and removes older standalone docs markdown files.

Reviewed changes

Copilot reviewed 63 out of 187 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
docs/drafts/providers/index.mdx	Provider overview + comparison content (draft).
docs/drafts/providers/anthropic.mdx	Anthropic provider setup content (draft).
docs/drafts/platforms/windows-wsl2.mdx	Windows WSL2 platform guide (draft).
docs/drafts/platforms/windows-native.mdx	Native Windows platform guide (draft).
docs/drafts/platforms/vps.mdx	VPS hardening guide (draft).
docs/drafts/platforms/raspberry-pi.mdx	Raspberry Pi deployment guide (draft).
docs/drafts/platforms/macos.mdx	macOS install + launchd guide (draft).
docs/drafts/platforms/linux.mdx	Linux install + systemd/security guide (draft).
docs/drafts/platforms/docker-compose.mdx	Docker Compose production deployment guide (draft).
docs/drafts/ops/websocket-sse.mdx	WebSocket/SSE streaming reference (draft).
docs/drafts/ops/orchestrator.mdx	Orchestrator internal API reference (draft).
docs/drafts/ops/logging.mdx	Logging/monitoring + SSE logs reference (draft).
docs/drafts/install/vps.mdx	VPS installation walkthrough (draft).
docs/drafts/install/updating.mdx	Upgrade / rollback procedures (draft).
docs/drafts/install/uninstalling.mdx	Uninstall instructions (draft).
docs/drafts/install/nearai-cloud.mdx	Managed hosting overview (draft).
docs/drafts/install/local.mdx	Local install steps across OSes (draft).
docs/drafts/install/index.mdx	Install landing page (draft).
docs/drafts/install/docker.mdx	Docker-based install walkthrough (draft).
docs/drafts/help/troubleshooting.mdx	Troubleshooting guide (draft).
docs/drafts/help/faq.mdx	FAQ content (draft).
docs/drafts/agents/skills-format.mdx	SKILL.md schema + examples (draft).
docs/drafts/agents/routines.mdx	Routines overview (draft).
docs/drafts/agents/memory-search.mdx	Hybrid search explanation (draft).
docs/drafts/agents/index.mdx	Agent architecture overview (draft).
docs/drafts/agents/clawhub.mdx	ClawHub registry usage (draft).
docs/docs.json	Mintlify site config + navigation.
docs/channels/webhook.mdx	HTTP webhook channel docs.
docs/channels/telegram.mdx	Telegram channel docs.
docs/channels/signal.mdx	Signal channel docs stub.
docs/channels/overview.mdx	Channels landing page.
docs/channels/local.md	Local channel (TUI + Web Gateway) docs.
docs/channels/discord.mdx	Discord channel docs.
docs/capabilities/skills.mdx	Skills capability docs.
docs/capabilities/sandboxed-tools.mdx	WASM sandboxed tools capability docs.
docs/capabilities/routines/reactive.mdx	Reactive routines docs.
docs/capabilities/routines/heartbeat.mdx	Heartbeat docs.
docs/capabilities/routines/cron.mdx	Cron routines docs.
docs/capabilities/overview.mdx	Capabilities landing page.
docs/capabilities/memory/memory.mdx	Persistent memory docs.
docs/capabilities/memory/identity.mdx	Identity files docs.
docs/capabilities/jobs/self-repair.mdx	Self-repair/stuck jobs docs.
docs/capabilities/jobs/jobs.mdx	Jobs + parallel execution docs.
docs/TELEGRAM_SETUP.md	Removes legacy Telegram setup doc (superseded).
docs/LLM_PROVIDERS.md	Removes legacy LLM providers doc (superseded).
docs/.mintignore	Excludes drafts/internal/plans from Mintlify build.
docs/.gitignore	Ignores node_modules and env screenshot artifacts.
README.zh-CN.md	Updates doc links to new structure.
README.ru.md	Updates doc links to new structure.
README.md	Updates doc links to new structure.
README.ko.md	Updates doc links to new structure.
README.ja.md	Updates doc links to new structure.
CONTRIBUTING.md	Adds guidance for documenting changes + Mintlify commands.
.claude/skills/mintlify-docs	Adds Claude skill link for Mintlify docs guidance.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-09T09:53:08Z

+# Allow Web Gateway
+sudo ufw allow 3000/tcp
+
+# Allow HTTP Webhook (if using)
+sudo ufw allow 8080/tcp


This firewall guidance contradicts other docs in this PR that warn against exposing the Web Gateway/HTTP Webhook directly to the internet (and recommend a TLS-terminating reverse proxy). Exposing 3000/8080 publicly increases attack surface and risks accidental unauthenticated access if tokens/secrets are weak or misconfigured. Prefer binding services to localhost and opening only 80/443 (reverse proxy), or at minimum restrict 3000/8080 to trusted source IPs/VPN interfaces.

Suggested change

# Allow Web Gateway

sudo ufw allow 3000/tcp

# Allow HTTP Webhook (if using)

sudo ufw allow 8080/tcp

# Allow reverse proxy only

sudo ufw allow 80/tcp

sudo ufw allow 443/tcp

# Do NOT expose the Web Gateway (3000) or HTTP Webhook (8080) directly to the internet.

# Keep them bound to localhost and route traffic through the TLS-terminating reverse proxy.

Copilot · 2026-04-09T09:53:09Z

+launchctl unload ~/Library/LaunchAgents/ai.ironclaw.service.plist
+launchctl load ~/Library/LaunchAgents/ai.ironclaw.service.plist


The LaunchAgent filename here doesn't match the macOS setup doc in this PR, which instructs creating ~/Library/LaunchAgents/ai.ironclaw.plist. This would cause the update instructions to fail if users followed the macOS guide. Align the filename across macOS install/update/uninstall docs (either consistently use ai.ironclaw.plist or consistently use ai.ironclaw.service.plist).

Suggested change

launchctl unload ~/Library/LaunchAgents/ai.ironclaw.service.plist

launchctl load ~/Library/LaunchAgents/ai.ironclaw.service.plist

launchctl unload ~/Library/LaunchAgents/ai.ironclaw.plist

launchctl load ~/Library/LaunchAgents/ai.ironclaw.plist

Copilot · 2026-04-09T09:53:09Z

+docker run -d \
+  --name ironclaw \
+  -v ~/.ironclaw:/home/ironclaw/.ironclaw \
+  # enabling this mount will allow the container to control the docker daemon, use at own risk
+  # -v /var/run/docker.sock:/var/run/docker.sock \
+  -p 3000:3000 \
+  -p 8080:8080 \
+  # Pin to a specific IronClaw version for reproducible, rollback-friendly deployments.
+  nearai/ironclaw:latest 


This example publishes ports 3000/8080 on all interfaces and also says to 'pin to a specific version' while using :latest. For safer defaults and to match other docs in this PR, bind to localhost (e.g., 127.0.0.1:3000:3000) and either use a concrete version tag or remove the pinning comment. This reduces accidental public exposure and improves reproducibility.

Copilot · 2026-04-09T09:53:09Z

+# Reference it in your .env
+IRONCLAW_MASTER_KEY=$(cat ~/.ironclaw/master.key)


This suggests using command substitution inside an .env file. If IronClaw loads .env via a dotenv parser (common), $(...) will not be evaluated and the literal string may be used, breaking secrets decryption. Recommend instructing users to paste the actual key value into .env (as a plain IRONCLAW_MASTER_KEY=...), or explicitly indicate they must source the file in a shell if command substitution is intended.

Suggested change

# Reference it in your .env

IRONCLAW_MASTER_KEY=$(cat ~/.ironclaw/master.key)

# Print the key, then copy the output into your .env as a literal value:

cat ~/.ironclaw/master.key

# In .env, paste the actual printed key value:

# IRONCLAW_MASTER_KEY=PASTE_THE_OUTPUT_HERE

Copilot · 2026-04-09T09:53:10Z

+    sudo apt install gnome-keyring
+
+    # Or use environment variable mode
+    export SECRETS_MASTER_KEY="your-key"


The environment variable name here conflicts with the rest of the docs in this PR, which consistently reference IRONCLAW_MASTER_KEY. If SECRETS_MASTER_KEY is not recognized by the app, users will be unable to decrypt stored secrets. Switch this to the correct env var name (or document both if both are supported).

Suggested change

export SECRETS_MASTER_KEY="your-key"

export IRONCLAW_MASTER_KEY="your-key"

Copilot · 2026-04-09T09:53:10Z

+| Provider | Backend | Local | Privacy | Cost | Best For |
+|----------|---------|-------|---------|------|----------|
+| **NEAR AI** | `nearai` | ✗ | ★★★ | $ | Default, easy setup |
+| **Anthropic** | `anthropic` | ✗ | ★★★ | $$ | Claude models |
+| **OpenAI** | `openai` | ✗ | ★★ | $$ | GPT models |
+| **Ollama** | `ollama` | ✓ | ★★★★★ | Free | Local inference |


These tables use a leading ||, which typically renders as an extra empty first column in standard Markdown. If this is intended for Mintlify, it would help to confirm; otherwise, switch to standard table syntax (single leading | or no leading pipe) to avoid a blank column and improve rendering consistency.

Copilot · 2026-04-09T09:53:10Z

 ```

-See [docs/LLM_PROVIDERS.md](docs/LLM_PROVIDERS.md) for a full provider guide.
+See [docs/capabilities/llm-providers.md](docs/capabilities/llm-providers.md) for a full provider guide.


This link targets docs/capabilities/llm-providers.md, but the Mintlify docs in this PR predominantly use .mdx files and Mintlify routes (e.g., capabilities/llm-providers). Ensure the linked file path exists in-repo as written (including extension), or update the README to point to the correct file/route to avoid a broken link on GitHub.

Suggested change

See [docs/capabilities/llm-providers.md](docs/capabilities/llm-providers.md) for a full provider guide.

See [docs/capabilities/llm-providers.mdx](docs/capabilities/llm-providers.mdx) for a full provider guide.

gemini-code-assist · 2026-04-09T09:58:29Z

Warning

Gemini is experiencing higher than usual traffic and was unable to create the review. Please try again in a few hours by commenting /gemini review.

claude · 2026-04-09T13:35:28Z

Code review

Found 5 issues:

[CRITICAL:HIGH] Missing activation section in SKILL.md

The mintlify skill has no activation criteria (patterns, keywords, exclude_keywords, tags, max_context_tokens). Without this, the skill scoring pipeline won't select it—the system has no way to determine when it's relevant to a user query. Every SKILL.md must define activation thresholds.

https://github.com/anthropics/ironclaw/blob/13c458e30cff5c437dfe3d19ddee0522f0c6e4fa/.claude/skills/mintlify-docs/SKILL.md#L1-L8

[CRITICAL:HIGH] Malformed metadata structure in SKILL.md

version is nested under metadata.version instead of at the root level per the spec. The spec requires version: X.Y.Z as a top-level field. Also, metadata.author doesn't match the required metadata.openclaw.requires structure for prerequisites. See .claude/rules/skills.md for the required format.

https://github.com/anthropics/ironclaw/blob/13c458e30cff5c437dfe3d19ddee0522f0c6e4fa/.claude/skills/mintlify-docs/SKILL.md#L1-L8

[HIGH:HIGH] Non-standard fields in SKILL.md frontmatter

Fields license: MIT and compatibility: ... are not in the SKILL.md spec (see .claude/rules/skills.md). These appear to be npm package.json conventions—remove them or move to a non-frontmatter section.

https://github.com/anthropics/ironclaw/blob/13c458e30cff5c437dfe3d19ddee0522f0c6e4fa/.claude/skills/mintlify-docs/SKILL.md#L1-L8

[MEDIUM:HIGH] Relative path links instead of root-relative paths in documentation

Multiple files use relative paths (./, ../) instead of root-relative paths (/) for internal links, violating Mintlify conventions and causing broken links:

docs/tunnel.mdx line 9: (./quickstart) should be (/quickstart)
docs/quickstart.mdx line 132: (./channels/telegram) should be (/channels/telegram)
docs/channels/discord.mdx line 9: (../quickstart) should be (/quickstart)
docs/zh/quickstart.mdx line 132: (./channels/telegram) should be (/channels/telegram)
docs/extensions/google/*.mdx files: (./oauth-setup) should be (/extensions/google/oauth-setup)

https://github.com/anthropics/ironclaw/blob/13c458e30cff5c437dfe3d19ddee0522f0c6e4fa/docs/tunnel.mdx#L8-L10

[LOW:MEDIUM] Missing prerequisite gating for Node.js and Git

The SKILL.md notes Node.js and Git requirements in the compatibility text, but has no metadata.openclaw.requires section with bins: [node, git] for the gating pipeline. Users might attempt to use the skill without these tools available.

https://github.com/anthropics/ironclaw/blob/13c458e30cff5c437dfe3d19ddee0522f0c6e4fa/.claude/skills/mintlify-docs/SKILL.md#L1-L8

Guillermo Alejandro Gallardo Diez and others added 28 commits March 13, 2026 16:52

feat: basic setup and telegram

3911ee5

Rename project to IronClaw and update documentation

2f70969

Updated the README to reflect the new project name and removed references to the Mintlify Starter Kit.

feat: added extensions

6f477be

Merge branch 'main' of github.com:nearai/ironclaw-docs

9593410

fix: links in the sidebar

e960492

feat: add github extension

6718470

chore: add update command

a66afcb

feat: added more channels

604ed4f

Merge pull request nearai#30 from nearai/channels

115ac2b

feat: added more channels

feat: add zh support for documentation

a3e8ccf

feat(i18n): navbar

de98cae

fix: improve landing & quickstart

865cb8e

Merge pull request nearai#33 from nearai/feat/zh-i18n

f2dd7ee

feat: add Chinese (zh) internationalization for documentation

chore: add self-repair

91993d3

feat: add google calendar tool tutorial (nearai#34)

0c9a57f

feat: add tutorial on hosting ironclaw through droplet (nearai#36)

fd210c6

Co-authored-by: Guillermo Alejandro Gallardo Diez <gagdiez@iR2.local>

feat: add overview to channels & extensions

3483018

feat: add security section & fix broken links

9fec477

chore: zh translations

0826c7c

chore: remove redundant google name from all google tools

856b620

feat: added discord

f60aeae

chore: temporarily move docs to new folder

2bc6929

Add 'docs/' from commit 'f60aeaece3d40384de726347281121281bcd0a05'

115a370

git-subtree-dir: docs git-subtree-mainline: 2bc6929 git-subtree-split: f60aeae

chore: migrate all engineer docs to docs

7ece881

chore: updated contributing and readme files

d881c03

chore: add mintlify skills to help agents write docs

a8991ec

Copilot AI review requested due to automatic review settings April 9, 2026 09:51

github-actions Bot added the scope: docs Documentation label Apr 9, 2026

github-actions Bot added size: XL 500+ changed lines risk: low Changes to docs, tests, or low-risk modules contributor: new First-time contributor labels Apr 9, 2026

fix: mintlify skills

b9779c5

Copilot AI reviewed Apr 9, 2026

View reviewed changes

chore: remove unnecesary files

9745975

frol approved these changes Apr 9, 2026

View reviewed changes

frol changed the title ~~Add mintlify docs~~ docs: Add mintlify docs Apr 9, 2026

frol merged commit 13c458e into nearai:staging Apr 9, 2026
13 of 14 checks passed

gagdiez mentioned this pull request Apr 9, 2026

Migrate documentation from https://github.com/nearai/ironclaw-docs #2188

Closed

gagdiez deleted the add-mintlify-docs branch April 9, 2026 13:30

ironclaw-ci Bot mentioned this pull request Apr 9, 2026

chore: promote staging to staging-promote/6895cdad-24185214226 (2026-04-09 13:31 UTC) #2197

Merged

github-actions Bot mentioned this pull request Apr 10, 2026

chore: promote staging to staging-promote/6fa2d0ec-24071779175 (2026-04-07 10:20 UTC) #2106

Merged

ironclaw-ci Bot mentioned this pull request Apr 10, 2026

chore: release #2075

Merged

ironclaw-ci Bot mentioned this pull request Apr 18, 2026

chore: release #2606

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Add mintlify docs#2189

docs: Add mintlify docs#2189
frol merged 30 commits intonearai:stagingfrom
gagdiez:add-mintlify-docs

gagdiez commented Apr 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 9, 2026

Uh oh!

Copilot AI Apr 9, 2026

Uh oh!

Copilot AI Apr 9, 2026

Uh oh!

Copilot AI Apr 9, 2026

Uh oh!

Copilot AI Apr 9, 2026

Uh oh!

Copilot AI Apr 9, 2026

Uh oh!

Copilot AI Apr 9, 2026

Uh oh!

gemini-code-assist Bot commented Apr 9, 2026

Uh oh!

Uh oh!

claude Bot commented Apr 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

-# Allow Web Gateway
-sudo ufw allow 3000/tcp
-# Allow HTTP Webhook (if using)
-sudo ufw allow 8080/tcp
+# Allow reverse proxy only
+sudo ufw allow 80/tcp
+sudo ufw allow 443/tcp
+# Do NOT expose the Web Gateway (3000) or HTTP Webhook (8080) directly to the internet.
+# Keep them bound to localhost and route traffic through the TLS-terminating reverse proxy.

		launchctl unload ~/Library/LaunchAgents/ai.ironclaw.service.plist
		launchctl load ~/Library/LaunchAgents/ai.ironclaw.service.plist

		# Reference it in your .env
		IRONCLAW_MASTER_KEY=$(cat ~/.ironclaw/master.key)

	export SECRETS_MASTER_KEY="your-key"
	export IRONCLAW_MASTER_KEY="your-key"

	See [docs/capabilities/llm-providers.md](docs/capabilities/llm-providers.md) for a full provider guide.
	See [docs/capabilities/llm-providers.mdx](docs/capabilities/llm-providers.mdx) for a full provider guide.

Conversation

gagdiez commented Apr 9, 2026

Summary

Change Type

Linked Issue

Validation

Security Impact

Database Impact

Blast Radius

Review Follow-Through

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot commented Apr 9, 2026

Uh oh!

Uh oh!

claude Bot commented Apr 9, 2026

Code review

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants