mirror of
https://github.com/nearai/ironclaw.git
synced 2026-09-03 08:06:01 +08:00
automation/codebase-graph-refresh
12 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
Josh Ford
|
6c680257e4 |
docs: move changelog to a navbar tab and tighten its intro (#7859)
* docs: move changelog to a navbar tab and tighten its intro Replace the bottom "Releases" sidebar group with Docs / Changelog navbar tabs (with icons), aligned to the content area's left edge via a CSS override of the almond theme's right-side tab placement. Rewrite the changelog intro into three single-idea sentences. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XTZsoEbLEd6rPKmKqbYsU5 * docs: anchor navbar tabs at the documented 272px content edge Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XTZsoEbLEd6rPKmKqbYsU5 * docs: shorten navbar tab CSS comment Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XTZsoEbLEd6rPKmKqbYsU5 --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com> |
||
|
Josh Ford
|
f75947032b |
release(docs): deploy public docs from a docs-live branch moved by stable releases (doc-truth PR 4/5) (#7379)
* release(docs): deploy public docs from a docs-live branch moved by stable releases The Mintlify GitHub App deployed docs/ on every push to main, so the public site described unreleased behavior while binaries shipped from ironclaw-v* tags — the root cause behind #7317's drift reports. The site now tracks the latest stable release: - .github/workflows/ironclaw-release.yml: new publish-docs-live job (after host, prerelease-guarded via the dist manifest's announcement_is_prerelease) force-updates refs/heads/docs-live to the released commit through the GitHub refs API, bootstrapping the branch on first run. Forced by design: successive stable tags need not be ancestor-related, and docs-live is a pointer, not a history. The Mintlify dashboard repoint to docs-live is the one out-of-repo step, documented in the release strategy. - scripts/ci/ws12_workflow_contracts.py: the job, the branch ref, and the prerelease guard join REQUIRED_MARKERS so a cargo-dist regeneration that drops the hand-added job fails Code Style instead of silently unhooking docs publication. - docs/changelog.mdx (new, in en nav under a Releases group): human-curated <Update> entry per stable release, seeded with v1.1.0 and v1.0.0 from the GitHub release notes; links tagged docs trees for older releases instead of maintaining versioned page sets. - scripts/ci/cut_ironclaw_release.py: ensure_stable_changelog_entry — a stable (non-rc) cut refuses when the candidate commit's changelog lacks the release's vX.Y.Z entry, with an actionable message; rc cuts are exempt so the freeze/blocker flow is unimpeded. Five new cases in test_cut_ironclaw_release.py (missing entry, missing file, present entry, rc exemption, malformed-version deferral to the canonical validator). - docs/internal/weekly-release-strategy.md: Monday checklist writes the changelog entry on the release branch; promotion notes the automatic docs-live repoint; new "Docs publication" section records the dashboard configuration, post-promotion verification, branch-protection recommendation, emergency manual repoint, and older-release access. End-to-end proof of the workflow job rides the next stable release; until the Mintlify dashboard is repointed the site keeps deploying from main, so the rollout order is: merge, repoint the dashboard, then the next stable tag takes over. Part of #7317 (doc-truth pipeline, PR 4 of 5). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * release(docs): harden the docs-live chain after review Three gaps found reviewing the pipeline end to end: - Changelog history loss: the runbook told the release owner to write the changelog entry on the frozen release branch, which is never merged back — next week's candidate, cut from main, would ship a changelog missing the release and docs-live would silently drop it. The entry now lands on main before the Monday cut; the gate's message and the runbook say so, with a cherry-pick fallback. - Substring gate false-pass: the stable gate accepted any 'vX.Y.Z' substring, so an rc-labeled entry (description="vX.Y.Z-rc.1") or a prose mention satisfied it. It now requires the exact description="vX.Y.Z" attribute; both cases pinned in tests. - Backwards repoint: re-running an older release's workflow would force-move docs-live to the older commit and silently revert the live site. publish-docs-live now moves the pointer only when its own tag is the newest stable ironclaw-v* tag, and the guard is pinned in ws12 REQUIRED_MARKERS so regeneration cannot drop it. The runbook also gains the docs-hotfix recipe (publish tag+fix, never main) and spells out that docs-live branch protection must allow force pushes or it 422s the automation. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * release(docs): match a real changelog Update tag and fail the repoint closed Post-review hardening: the stable gate now requires the version on an actual <Update> tag (lookalike attributes and other elements refuse, with a regression test); the publish-docs-live step runs under set -euo pipefail and rejects empty tag discovery instead of silently skipping; ws12 pins the backward-repoint comparison itself; comments trimmed and the public changelog no longer overclaims while the dashboard still deploys from main. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * release(docs): close the review-round gaps in the docs-live chain Seed the changelog with v1.2.0 (already-shipped stable whose branch never merges back), put ironclaw-release.yml in code_style's has_code scope and pin that semantically in ws12, bootstrap docs-live via POST only when the branch truly does not exist so protection 422s surface as themselves, drive the changelog gate through main() in tests, restore the emergency paragraph to its own runbook section, and tell contributors docs reach the live site with the next stable release. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com> |
||
|
Elliot Braem
|
6254f4223f |
docs: adds documentation for IronHub (#6965)
* init gitignore * ironhub docs * add to building a tool * fix: address PR review feedback for IronHub docs - Anchor .gitignore app/ to /app/ so it doesn't silently ignore nested frontend app directories - Fix manifest format: JSON -> TOML in overview.mdx - Add missing Private provenance tier to provenance table - Replace false 'reduced tool access' claims with accurate content visibility + self-activation gating in installing.mdx and skills.mdx - Document --acknowledge-unverified flag for community entries - Add hub as visible_alias for the ironhub CLI subcommand * fix: correct trust claims in Chinese skills docs to match English Replace false tool-access attenuation claims with accurate content-visibility and self-activation gating — matching the English skills.mdx fix. * docs: add Chinese translations for IronHub hub pages Translate overview.mdx, installing.mdx, and contributing.mdx to Simplified Chinese. Content reflects the corrected trust claims (content-visibility and self-activation gating), TOML manifest format, Private provenance tier, and --acknowledge-unverified flag. * fix: add hub alias test, zh IronHub nav, and alias docs - Add ironhub_hub_alias_resolves smoke test verifying the 'hub' alias routes to the ironhub subcommand - Add IronHub nav group to the Chinese docs.json sidebar - Drop dead #provenance-tiers anchor on the zh contributing page - Document 'hub' as an accepted alias in reborn-binary.md * Update docs/zh/hub/installing.mdx Co-authored-by: Josh Ford <thisisjoshford@gmail.com> * Update docs/hub/installing.mdx Co-authored-by: Josh Ford <thisisjoshford@gmail.com> --------- Co-authored-by: Josh Ford <thisisjoshford@gmail.com> |
||
|
Elliot Braem
|
cf99a6c7b7 |
docs: upgrade documentation for IronClaw V1 (#6970)
* init gitignore * ironhub docs * upgrade docs for v1 * resolve comments |
||
|
Josh Ford
|
1fd85b2c45 |
docs: restructure the docs site around the shipped 1.0 binary (#6692)
* docs: stop publishing internal engineering docs to the public site
docs/.mintignore only excluded plans/ and internal/, so docs/reborn/,
superpowers/, qa/, adr/ and architecture-video/ were shipped to the
public Mintlify site. 33 internal architecture documents were live and
serving full content on docs.ironclaw.com, including the entire
reborn/contracts/ freeze set (kernel-boundary, secrets, capabilities,
trust-boundary-hardening, network, ...), the current architecture map,
and the product-manager architecture guide.
Verified by probing all 139 internal doc paths against the live site:
33 returned HTTP 200, 94 returned 404. The 404s were not protected by
policy -- they are simply newer than the last build -- so superpowers/
and the rest were exposed to the same leak on any rebuild.
Files stay where they are so they keep versioning with the code and
stay reachable by the knowledge graph; only publication changes.
No navigation page lives under a newly ignored path, so the public
site's page set is unchanged.
* docs: rewrite get-started pages against the shipped binary
The quickstart told users to start the agent by running `ironclaw` with
no arguments. The shipped 1.0.0-rc.1 binary requires a subcommand and
exits with code 2 and a usage error, so step 2 could not succeed.
Verified against the released binary rather than the source tree:
- install -> `ironclaw onboard` -> `ironclaw serve` is the real path;
onboarding prints a `login_link` with the web token
- onboarding writes config.toml, providers.json, webui-token and
.onboard-completed.json under ~/.ironclaw/reborn, and provisions the
master key in the OS keychain
- `serve` listens on 127.0.0.1:3000 and takes --host/--port
- real onboard flags are --force/--dry-run/--no-service/--import-history,
and --import-history is not wired up yet
Also drops the v1 onboarding steps that no longer exist (database
backend picker, embeddings toggle, tunnel/channel wizard, Docker
sandbox prompt), removes the stale PID-file troubleshooting for a
codepath the Reborn binary does not have, fixes the /channels and
/capabilities/jobs links on the index page, and corrects the provider
count from "7+" to 25+.
Removes the /home/agent and /home/user absolute paths flagged by
.claude/rules/doc-hygiene.md.
* docs: document the web interface, CLI, service, and Trace Commons
None of the shipped binary's primary surfaces had a page. The site
documented an agent you configure with environment variables and talk
to in a terminal; the product is a web application you start with
`ironclaw serve` and administer from the browser.
Adds four pages, all written from the verified 1.0.0-rc.1 command tree
rather than the source tree:
- using/webui: serve flags and defaults (127.0.0.1:3000), the
webui-token login link, Google/GitHub SSO env vars, and the visible
surfaces. Notes that sessions carry user identity only and do not
inherit operator config privileges.
- using/cli: the full command surface. Flags `channels list`,
`hooks list` and `logs` as registered-but-unimplemented so readers
do not file bugs against known stubs.
- using/service: launchd/systemd unit naming, log paths under
~/.ironclaw/reborn/logs, and the headless master-key note.
- capabilities/traces: the Trace Commons opt-in, preview/submit/revoke
flow, and instance enrollment. Calls out that bare `traces opt-out`
on an enrolled instance disables the whole enrollment.
Documents only the SPA routes that are actually in the sidebar;
Projects/Jobs/Routines/Missions/Logs are registered but hidden while
their v2 APIs land, and the page says so rather than describing a
sidebar entry that is not there.
* docs: rewrite configuration and storage against the real config model
The configuration page documented a ~/.ironclaw/.env bootstrap layer
plus database-backed settings, and cited src/config/ as its source of
truth. src/ no longer exists. None of DATABASE_BACKEND, DATABASE_URL,
LIBSQL_PATH, LLM_BACKEND, HTTP_PORT or SECRETS_MASTER_KEY are read by
the shipped binary.
Rewritten from `ironclaw config list`, `config path`, `config init`
output and the generated config.toml on 1.0.0-rc.1:
- config.toml (selection) + providers.json (catalog) under
~/.ironclaw/reborn, both optional
- precedence: compiled defaults < config.toml < env < CLI flags
- secrets referenced by env var NAME; pasting a value is rejected at
parse time
- the six real boot profiles, flagged as a security boundary
- real key groups incl. budget.* and trigger_poller.*, neither of
which was documented anywhere
- IRONCLAW_REBORN_* override namespace
Storage: the page claimed PostgreSQL is the default and that starting
without DATABASE_URL fails. The shipped StorageBackend enum has one
variant, Postgres, and local-dev stores state in embedded database
files with no server at all. Rewritten around that, keeping the
pgvector setup and adding the pool-sizing and sslmode=require notes
from the generated config comments.
Inference providers: the catalog is 26 built-in providers, not the 17
listed. OpenRouter, Together and Fireworks are first-class provider
ids rather than openai_compatible aliases, and Groq, DeepSeek,
Cerebras, SambaNova, Venice, NVIDIA, Z.AI, Tinfoil, native Gemini and
openai_codex were missing entirely. Every api_key_env in the table is
taken from providers.json. Also drops `ironclaw onboard
--provider-only`, which is not a real flag, in favour of
`ironclaw models set-provider`.
Deletes tunnel.mdx and zh/tunnel.mdx. Tunnels have no Reborn
implementation: no tunnel.* config key, no Rust source reference, and
the WebUI networking settings section is commented out. Removes the
now-dangling tunnel card from the channels overview.
* docs: cut channels to what the 1.0 binary actually supports
The site documented seven channels. The Reborn stack implements two.
Deleted, with no implementation in crates/:
- discord: appears only in comments and test fixtures as a
hypothetical future package
- signal: every match is a unix-signal or state-signal identifier,
not a messenger
- wechat / wecom: wechat survives only as the standalone
ironclaw_silk_decoder voice helper; wecom has zero references
- local: documented the v1 Ratatui terminal UI and web gateway with
GATEWAY_*/HTTP_* env vars. The real equivalents are `ironclaw repl`
and `ironclaw serve`, now covered under Using IronClaw.
- webhook: documented a standalone webhook channel with a shared
secret and HTTP_* config. No such config key exists; webhook ingress
now belongs to the extension host and serves Slack/Telegram events.
Telegram rewritten: the old page told users to run
`ironclaw onboard --channels-only`, which is not a real flag. Setup is
now WebUI channel setup plus the pairing step, with the real
/webhooks/telegram/updates callback.
Slack added. It has a first-party package, a v2 adapter, a [slack]
config section and a live /webhooks/extensions/slack/events route, and
had no page at all.
The overview says plainly that Discord, Signal, WeChat and WeCom were
v1 features and are not in 1.0, so readers who used them know to stay
on v1 rather than assume the docs are broken.
* docs: correct Responses API prerequisites and auth
The endpoints themselves are real and covered by
crates/ironclaw_reborn_composition/tests/webui_v2_serve.rs, but the
page's prerequisites were not.
- Drops the note requiring ENGINE_V2=true for external tools. Engine
v2 was removed; the only trace left in the tree is a stale comment.
Requests with tools[] no longer depend on a server flag.
- Replaces GATEWAY_AUTH_TOKEN and the self-service /api/tokens CRUD
surface, neither of which exists in crates/, with the real auth
paths: the onboarding-provisioned webui-token (or
IRONCLAW_REBORN_WEBUI_TOKEN) for single-user, and admin-minted
one-time per-user bearers via /api/webchat/v2/admin/users.
- Notes that the instance token is an operator credential while
per-user and SSO bearers carry user identity only, matching the
privilege split the gateway actually enforces.
* docs: replace extension commands that do not exist, consolidate MCP
Fourteen published pages taught commands the shipped binary does not
have. `ironclaw tool`, `ironclaw registry`, `ironclaw mcp` and
`ironclaw pairing` were v1 CLI subcommands; the Reborn CLI exposes
`ironclaw extension {search,install,activate,remove}` instead.
Rewrote the invocations across the Google suite, GitHub, web-search and
sandboxed-tools, and corrected the authorization prose: activating an
extension starts its setup flow, which is completed from Extensions in
the web interface, not from a CLI auth subcommand.
MCP had two pages, both built entirely on the nonexistent
`ironclaw mcp` CLI (add/list/test/toggle/remove/auth). Consolidated
into extensions/mcp and deleted capabilities/mcp, since MCP is a
runtime an extension declares rather than a capability of its own.
The stdio and Unix-socket transports the old page documented are not
supported: ironclaw_mcp rejects stdio outright ("unsupported until
process-level egress controls land"). The page now says HTTP only and
warns about stdio instead of giving instructions that cannot work.
Adds redirects for every page removed in this branch (capabilities/mcp,
tunnel, and the six retired channels) so existing inbound links land
somewhere useful instead of 404ing.
Full internal-link audit across all published English pages: 0 broken.
* docs: fix hosting guides and reconcile zh with the new structure
The three hosting tutorials ended with `ironclaw` as the start command,
so a reader who followed DigitalOcean, GCP or AWS end to end hit the
same usage error as the quickstart. They now run `onboard` then
`serve`, forward the port over SSH instead of exposing it, and install
the service so the agent survives disconnect.
Retires GATEWAY_AUTH_TOKEN (infrastructure/google, extensions/shell) in
favour of IRONCLAW_REBORN_WEBUI_TOKEN.
Chinese pages: deleted the two orphans that were never in navigation
(zh/capabilities/jobs, zh/extensions/google-calendar), applied the same
command corrections across 14 pages, and rewrote zh/channels/overview,
which still advertised Local, Signal, WeChat, WeCom, Webhook and Tunnel
as live cards pointing at deleted pages.
Full audit across all 76 navigation pages in both languages: 0 broken
internal links, no page missing from disk.
Left as follow-up: zh/quickstart, zh/onboard, zh/extensions/mcp and
zh/channels/telegram still mirror the pre-rewrite English structure and
need retranslation, not mechanical patching. They are flagged rather
than half-translated.
The /home/ironclaw paths in the hosting guides are deliberate — they
are the server-side service account, not developer-local paths, so
doc-hygiene does not apply to them.
* docs: address PR review, pinned to the released 1.0.0-rc.1 surface
These docs describe the version users can install today. Ground truth
is the `ironclaw-v1.0.0-rc.1` tag and the released binary, not `main`.
Two review findings were verified as main-only drift and deliberately
not applied:
- `ironclaw` with no subcommand. main added args_with_default_serve in
|
||
|
Coffee
|
d1c100dca0 |
docs: document WeChat and WeCom channels (#3680)
* docs: wechat * docs: wechat * docs: document wecom channel setup * docs: address channel doc review comments * docs: localize Chinese channel names |
||
|
Illia Polosukhin
|
b921b42998 |
docs(api): document the Responses API end-to-end (#3709)
* docs(api): document the Responses API end-to-end Covers auth (gateway token vs per-user /api/tokens), session continuity via previous_response_id, streaming, externally-provided function tools (the engine-native round trip landed in #3122), structured x_context, per-request instructions, error envelope, and the current limits (one-call-per-turn, no tool_choice, no temperature). Wires the new page into docs.json under a top-level "API" group so it sits next to Channels and Extensions rather than buried under Capabilities. * docs(api): address PR #3709 review feedback Verified against the current code, not just the bot suggestions: - Auto-generated gateway token: 32 random bytes hex-encoded => 64 chars, not 32 (src/channels/web/mod.rs:118-121). - Token create response field: token_prefix, not prefix (src/channels/web/handlers/tokens.rs:92). - Streaming events: response.in_progress is defined but the worker only emits response.created (src/channels/web/responses_api.rs:1530-1536), so drop the row that promises an event clients never see. - Auth errors: the gateway middleware returns plain-text 401/403/503 before the request reaches the Responses handler (src/channels/web/platform/auth.rs:1133), not the JSON envelope. - previous_response_id ownership: 404 is the GET behavior only; POST decodes the UUID and dispatches into the agent (src/channels/web/responses_api.rs:1237-1244), so cross-user resume fails at the turn level, not via 404. - instructions caveat: IronClaw currently prepends the <instructions> block into the user message and persists it (responses_api.rs:1231-1234), so it does replay across turns even though the OpenAI spec promises one-turn semantics. - Anchor: #input-shapes never existed; point to #external-tools where the array form is actually shown. The Gemini bot also flagged `resp.output_text` as a phantom property across both SDK examples. Verified directly against openai-python/src/openai/types/responses/response.py:310-322 and openai-node/src/resources/responses/responses.ts:963 - both expose output_text as a convenience aggregator over output_text content blocks, and their own docstrings recommend it over walking output[0]. SDK examples kept as-is. |
||
|
Jean-Philippe Martel
|
d4451df8f0 |
docs: promote database and configuration pages from drafts to live
Move the existing database backends and configuration reference docs out of drafts/ and into the live navigation under Core Capabilities. - capabilities/database.mdx: PostgreSQL vs libSQL setup, env vars, SSL modes, hybrid search, migration, backup, troubleshooting - capabilities/configuration.mdx: full environment variable reference with two-layer config system - docs.json: add both pages to Core Capabilities nav group |
||
|
arc-claw-bot
|
2874d2e98f |
docs: MCP server configuration guide (#1138)
* docs: add MCP server configuration guide Covers the three transport types (HTTP, stdio, Unix), OAuth 2.1 authentication, environment variables for stdio servers, custom headers, the mcp-servers.json config format, example servers, and troubleshooting. Written against the current implementation in src/tools/mcp/ and src/cli/mcp.rs. * fix: docs * chore: better explain toggle --------- Co-authored-by: Guille <gagdiez.c@gmail.com> Co-authored-by: Guillermo Alejandro Gallardo Diez <gagdiez@iR2.local> |
||
|
matiasbenary
|
5140279bb4 |
docs: guide how to host ironclaw on google cloud (#2262)
* feat: add google turorial * feat: update zh google tutorial * feat: update firewall rules * feat: update zh files |
||
|
matiasbenary
|
494636d64a |
docs: add amazon tutorial (#2261)
* feat: add amazon tutorial * chore: apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Guille <gagdiez.c@gmail.com> * chore: apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Guille <gagdiez.c@gmail.com> --------- Co-authored-by: Guille <gagdiez.c@gmail.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> |
||
|
Guille
|
13c458e30c | docs: Add mintlify docs (#2189) |