mirror of
https://github.com/nearai/ironclaw.git
synced 2026-09-03 08:06:01 +08:00
automation/codebase-graph-refresh
5 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
Josh Ford
|
c145f6e522 |
test(docs): doc-fact contract tests for CLI, manifest, and Responses claims (doc-truth PR 3/5) (#7378)
* docs: fix live drift in extension, responses API, and channel docs
The public tutorial taught the retired manifest v2 authoring format
([[host_api]] / [capability_provider.tools] / runtime_credentials), which
the v3 parser hard-rejects, and never mentioned origin_gate_matrix; the
Responses API page claimed temperature is rejected (accepted 0.0-2.0 and
forwarded), claimed model must be "default" (any well-formed name <= 256
bytes), claimed max_output_tokens is rejected (accepted and ignored by DTO
policy), and omitted the required model field from every request example;
the channel tutorial pointed at two files that no longer exist.
- docs/extensions/building-a-tool.md: rewrite manifest sections to the v3
[[tools]] / [[tools.credentials]] / [auth.<vendor>] shape, document
origin_gate_matrix (origins, policies, ratchet), correct the hosted-MCP
[mcp] section, packaging via ironclaw_extension_support package modules,
and v3 test references; drop the nonexistent script runtime kind.
- docs/api/responses.mdx: correct model/temperature/tools/tool_choice
rejection rules, document unknown-field tolerance, add the required
model field to all 15 request examples.
- docs/channels/building-a-channel.mdx: replace dead
crates/ironclaw_first_party_extensions + available_extensions.rs
registration instructions with the current package-directory mechanism.
- docs/reborn/contracts/extensions.md: state that production manifests
author v3 (lowering into the v2 resolved model described there); label
the v2 examples as legacy.
- docs/reborn/how-to-port-tool-to-reborn.md: superseded banner pointing at
the v3 guides.
Part of #7317 (doc-truth pipeline, PR 1 of 5).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ci(check-guidance): extend the reference gate to the docs/ surface
The public Mintlify tree had no path-reference validation — a published
tutorial told contributors to edit files that no longer exist and nothing
caught it. check-guidance.py already owned the machinery (tracked-tree
resolution, fence exclusion, suppress markers, shrink-only debt, fail-closed
floors), so the docs surface joins the same gate rather than a fork.
- discover_guidance() now collects every tracked docs/**.md|.mdx: published
pages, the zh/ locale mirror, and the living contract corpus
docs/reborn/contracts/. Dated archives (docs/internal/, the non-contract
parts of docs/reborn/) are excluded as classes — measured 2026-08-07,
705 of 709 dangling docs references sat in those historical corpora, and
forcing dated plans/ADRs to track today's tree would either rewrite
history or drown KNOWN_MISSING.
- docs/ files extract backticked inline paths only; Mintlify markdown link
targets are site routes (extensionless pages, site-absolute /using/cli),
a different namespace than the tracked tree, so the link extractor is off
there by design.
- _reference_lines learns MDX comments ({/* ... */}), including
{/* check-guidance: path-ok */} as the .mdx suppress-marker form, with the
same one-reference-per-marker and multi-line semantics as HTML comments.
- Floors re-measured and re-dated (364 files / 2276 references; floors
180/1100), plus a dedicated MIN_DOCS_FILES=60 floor: the aggregate floors
sit below the guidance-only remainder, so the docs branch of discovery
silently breaking needs its own refusal. --json now reports docs_files.
- Fixes the four real dangles the new scan found in docs/reborn/contracts/
(moved nested_dispatch_stream.rs test home, retired event-store migrations
directory, loop_driver_host tests->src move). KNOWN_MISSING stays empty.
- Self-tests: 8 new cases (dangling docs path fails; Mintlify links are not
references; MDX marker suppresses exactly one reference; multi-line MDX
comment hides content; zh discovered; archives excluded but contracts
scanned; docs fence fails closed; docs floor refuses).
- ws12_workflow_contracts.py: docs/api/responses.mdx and docs/zh/index.mdx
join the has_guidance in-scope probes so a narrowed trigger regex cannot
silently skip the gate for public docs.
Part of #7317 (doc-truth pipeline, PR 2 of 5); stacked on #7375.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(docs): pin CLI, manifest, and Responses doc claims to code
Three deterministic doc-fact contract tests, each living in the crate that
owns the truth it checks, so the drift #7317 describes fails CI instead of
shipping:
- crates/app/ironclaw_cli/tests/docs_cli_reference.rs: parses the real
binary's --help and cross-checks docs/using/cli.mdx table rows both ways
(every visible subcommand documented, any alias form counting; every
documented command real), with a fail-closed row floor. Doc gaps this
surfaced are fixed here: ironhub had no rows at all, completion was
fence-only, and the Trace Commons table lacked the `ironclaw` prefix the
rest of the page uses.
- crates/extensions/ironclaw_extension_registry/tests/
docs_manifest_schema_version.rs: walks the published docs tree (the
frozen .mintignore fence mirrored as constants) and asserts zero
occurrences of the retired reborn.extension_manifest.v2 literal, fenced
code included; asserts building-a-tool.md names
MANIFEST_SCHEMA_VERSION_V3 verbatim and documents origin_gate_matrix.
- crates/product/ironclaw_openai_compat/tests/docs_responses_contract.rs:
docs/api/responses.mdx now carries a machine-readable
{/* doc-fact:responses-request-policy */} marker block (invisible when
rendered); the test parses it and drives every claim through the same
route-level seam as the sibling *_contract.rs suites — the marker's
values parameterize the assertions (temperature accepted at the
documented max and rejected just above it, model accepted at the byte
cap and rejected past it, tool_choice always 400, tools 400 without /
registered with external-tool wiring, empty tools treated as omitted,
unknown fields like max_output_tokens accepted and ignored, and one
request carrying every documented field accepted).
Part of #7317 (doc-truth pipeline, PR 3 of 5); stacked on #7376.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: address Copilot and CodeRabbit review on doc-drift PR
- responses.mdx: tool_choice is rejected only without external-tools wiring;
with external tools enabled it passes validation and is currently ignored
(validate_responses_supported_fields_with_external_tools never checks it).
- building-a-tool.md: clarify that effect-derived host ports are validation
vocabulary against the HostPortCatalog allowlist; adapters are built by
host-runtime services after authorization/obligations, never from manifests.
- how-to-port-tool-to-reborn.md: mark the decision tree's RuntimeKind targets
historical (v3 accepts only wasm|first_party; MCP is top-level [mcp];
process/CLI work is the sandbox lane).
- building-a-channel.mdx: document the user install flow — virtual package
root /system/extensions/<id>/manifest.toml, ironclaw extension search /
install <extension-id> (ID, not path), WebUI Extensions lifecycle.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(responses): align the limits bullet with the corrected tool_choice claim
The rejection list was corrected in the previous commit (tool_choice is
rejected only without external-tools wiring); the "Limits and quirks"
bullet still said "not supported ... rejected with 400". Same claim, one
wording.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(docs): tool_choice is conditionally rejected, not always
Copilot review on the docs PR caught that
validate_responses_supported_fields_with_external_tools never checks
tool_choice — with external tools wired it is accepted and ignored, not
400'd. The doc-fact marker moves tool_choice into
rejected_without_external_tools, and the dedicated test now proves both
sides: 400 naming the param on the plain router, accepted-and-ignored
(submit succeeds, nothing registers) with external-tool wiring.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: apply verified code-review findings on the drift PR
A full code review of this PR against live code surfaced claims the
original drift pass got wrong or missed; every fix below was re-verified
against the cited source before editing:
- responses.mdx: standard `ironclaw serve` deployments always wire
external tools (OpenAiCompatRouteMountPorts requires the store/resume
pair; mount.rs wires them unconditionally), so `tools` is accepted and
`tool_choice` is accepted-and-ignored on shipped binaries — the
conditional 400s apply only to custom compositions without the wiring
(now a Note). temperature is validated and carried in the submitted turn
payload but not applied as a provider sampling parameter. Non-streaming
wait timeout is 30 s (DEFAULT_RESPONSES_WAIT_TIMEOUT), not 120. usage on
retrieval is read best-effort from persisted run state incl. USD cost
(read_run_usage), not always zero.
- building-a-tool.md: the [auth.example] oauth2_code recipe gains the
required token_response map (deny_unknown_fields rejects the example as
previously written); Gmail/Google Calendar corrected to first_party
runtimes (their manifests declare kind = "first_party"); the worked
api_key recipe is github's, not slack's; the tail "Quick implementation
checklist" and reference list were still v2-era (script lane,
assets/<extension>/ path, "manifest v2", v2.rs pointer) and now teach
the v3 shape; composition/CLI package-naming claim narrowed (the binary
does link slack/telegram adapter crates).
- contracts/extensions.md: legacy-format paragraph no longer claims
host-bundled packages ship v2 (none do), and origin_gate_matrix is
attributed to capability.rs + building-a-tool.md instead of
extension-runtime/overview.md §3, which does not mention it.
- how-to-port banner: `script` manifest authoring is retired; the
RuntimeKind::Script symbol survives as the process-sandbox lane's kind.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(contracts): repoint delivery_resolution.rs to its family directory
PR #7157 (merged to main 2026-08-07) cited
crates/ironclaw_outbound/src/delivery_resolution.rs in the
communication-delivery-resolution contract; the crate lives at
crates/domains/ironclaw_outbound/. Caught by this branch's docs surface of
check-guidance.py on the first merge of main after the gate landed —
exactly the drift class it exists for.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ci(test-plan): route docs pages to the doc-fact tests that read them
docs/ sat in IGNORED_PREFIXES as a pure-prose class, which this PR's
doc-fact tests falsify: three cargo tests now read published pages, so
a docs-only PR would have selected zero crate tests and merged green,
leaving the failure to land on whichever unrelated change ran the full
plan next.
Published Markdown now selects the registry's schema-version sweep;
docs/using/cli.mdx and docs/api/responses.mdx additionally select
their owning crates. All selections are direct exact test targets —
no reverse-dependency widening, since prose only changes the doc-fact
assertions that read it. Fenced trees (docs/internal/, docs/reborn/,
drafts) and non-page files keep the prose classification.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ci(check-guidance): harden the docs gate and fix review-surfaced doc drift
Applies the verified findings from the PR #7376 code review:
- The loop-exit and turn-runner contract docs claimed the deleted
loop_driver_host checkpoint-rejection test had 'moved into the
module'; it was deleted in #6696 and the fenced verification command
could not run. Both now cite the real surviving pins
(planned_driver.rs executor test + the ironclaw_turns projection
test mapped in scripts/reborn-e2e-rust.sh), with runnable commands.
- An unterminated comment now refuses at EOF like an unterminated
fence; before, one typo'd closer silently un-scanned the rest of the
file.
- Markdown links in the re-included corpora are now checked as repo
paths (they are never published, so the Mintlify-route rationale did
not apply); this alone added ~165 verified references.
- Each DOCS_REINCLUDED_PREFIXES entry must match at least one tracked
page or discovery refuses, so the planned docs/reborn consolidation
cannot silently drop the corpus from the scan.
- The living extension-runtime spec pages (overview.md,
standard-operations.md) and guidance-conventions.md join the scan;
guidance-conventions.md now describes the docs surface and the MDX
marker form, and its one dangling test path is repointed.
- Floors comment corrected (57 rule globs, not 38).
Also fixes four drifted claims from #7375's pages, verified against
live code: the interleaved function_call_output example was rejected
with 400 (resume input must be exclusively function_call_output items
with previous_response_id); model is echoed only on create (GET/cancel
report the 'reborn' placeholder); output_schema_ref is optional; and
the unknown-fields claim now names the two deliberate exemptions.
Self-tests: 43 pass (three new arms — unterminated comment refusal in
both syntaxes, re-included links as repo claims, stale re-included
prefix refusal).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ci(check-guidance): sync module docstring with re-included link checking
CodeRabbit caught the docstring still claiming the link extractor is
off for all of docs/** — stale since
|
||
|
Josh Ford
|
d82c9584e5 |
ci(check-guidance): extend the reference gate to the docs/ surface (doc-truth PR 2/5) (#7376)
* docs: fix live drift in extension, responses API, and channel docs
The public tutorial taught the retired manifest v2 authoring format
([[host_api]] / [capability_provider.tools] / runtime_credentials), which
the v3 parser hard-rejects, and never mentioned origin_gate_matrix; the
Responses API page claimed temperature is rejected (accepted 0.0-2.0 and
forwarded), claimed model must be "default" (any well-formed name <= 256
bytes), claimed max_output_tokens is rejected (accepted and ignored by DTO
policy), and omitted the required model field from every request example;
the channel tutorial pointed at two files that no longer exist.
- docs/extensions/building-a-tool.md: rewrite manifest sections to the v3
[[tools]] / [[tools.credentials]] / [auth.<vendor>] shape, document
origin_gate_matrix (origins, policies, ratchet), correct the hosted-MCP
[mcp] section, packaging via ironclaw_extension_support package modules,
and v3 test references; drop the nonexistent script runtime kind.
- docs/api/responses.mdx: correct model/temperature/tools/tool_choice
rejection rules, document unknown-field tolerance, add the required
model field to all 15 request examples.
- docs/channels/building-a-channel.mdx: replace dead
crates/ironclaw_first_party_extensions + available_extensions.rs
registration instructions with the current package-directory mechanism.
- docs/reborn/contracts/extensions.md: state that production manifests
author v3 (lowering into the v2 resolved model described there); label
the v2 examples as legacy.
- docs/reborn/how-to-port-tool-to-reborn.md: superseded banner pointing at
the v3 guides.
Part of #7317 (doc-truth pipeline, PR 1 of 5).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ci(check-guidance): extend the reference gate to the docs/ surface
The public Mintlify tree had no path-reference validation — a published
tutorial told contributors to edit files that no longer exist and nothing
caught it. check-guidance.py already owned the machinery (tracked-tree
resolution, fence exclusion, suppress markers, shrink-only debt, fail-closed
floors), so the docs surface joins the same gate rather than a fork.
- discover_guidance() now collects every tracked docs/**.md|.mdx: published
pages, the zh/ locale mirror, and the living contract corpus
docs/reborn/contracts/. Dated archives (docs/internal/, the non-contract
parts of docs/reborn/) are excluded as classes — measured 2026-08-07,
705 of 709 dangling docs references sat in those historical corpora, and
forcing dated plans/ADRs to track today's tree would either rewrite
history or drown KNOWN_MISSING.
- docs/ files extract backticked inline paths only; Mintlify markdown link
targets are site routes (extensionless pages, site-absolute /using/cli),
a different namespace than the tracked tree, so the link extractor is off
there by design.
- _reference_lines learns MDX comments ({/* ... */}), including
{/* check-guidance: path-ok */} as the .mdx suppress-marker form, with the
same one-reference-per-marker and multi-line semantics as HTML comments.
- Floors re-measured and re-dated (364 files / 2276 references; floors
180/1100), plus a dedicated MIN_DOCS_FILES=60 floor: the aggregate floors
sit below the guidance-only remainder, so the docs branch of discovery
silently breaking needs its own refusal. --json now reports docs_files.
- Fixes the four real dangles the new scan found in docs/reborn/contracts/
(moved nested_dispatch_stream.rs test home, retired event-store migrations
directory, loop_driver_host tests->src move). KNOWN_MISSING stays empty.
- Self-tests: 8 new cases (dangling docs path fails; Mintlify links are not
references; MDX marker suppresses exactly one reference; multi-line MDX
comment hides content; zh discovered; archives excluded but contracts
scanned; docs fence fails closed; docs floor refuses).
- ws12_workflow_contracts.py: docs/api/responses.mdx and docs/zh/index.mdx
join the has_guidance in-scope probes so a narrowed trigger regex cannot
silently skip the gate for public docs.
Part of #7317 (doc-truth pipeline, PR 2 of 5); stacked on #7375.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: address Copilot and CodeRabbit review on doc-drift PR
- responses.mdx: tool_choice is rejected only without external-tools wiring;
with external tools enabled it passes validation and is currently ignored
(validate_responses_supported_fields_with_external_tools never checks it).
- building-a-tool.md: clarify that effect-derived host ports are validation
vocabulary against the HostPortCatalog allowlist; adapters are built by
host-runtime services after authorization/obligations, never from manifests.
- how-to-port-tool-to-reborn.md: mark the decision tree's RuntimeKind targets
historical (v3 accepts only wasm|first_party; MCP is top-level [mcp];
process/CLI work is the sandbox lane).
- building-a-channel.mdx: document the user install flow — virtual package
root /system/extensions/<id>/manifest.toml, ironclaw extension search /
install <extension-id> (ID, not path), WebUI Extensions lifecycle.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(responses): align the limits bullet with the corrected tool_choice claim
The rejection list was corrected in the previous commit (tool_choice is
rejected only without external-tools wiring); the "Limits and quirks"
bullet still said "not supported ... rejected with 400". Same claim, one
wording.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: apply verified code-review findings on the drift PR
A full code review of this PR against live code surfaced claims the
original drift pass got wrong or missed; every fix below was re-verified
against the cited source before editing:
- responses.mdx: standard `ironclaw serve` deployments always wire
external tools (OpenAiCompatRouteMountPorts requires the store/resume
pair; mount.rs wires them unconditionally), so `tools` is accepted and
`tool_choice` is accepted-and-ignored on shipped binaries — the
conditional 400s apply only to custom compositions without the wiring
(now a Note). temperature is validated and carried in the submitted turn
payload but not applied as a provider sampling parameter. Non-streaming
wait timeout is 30 s (DEFAULT_RESPONSES_WAIT_TIMEOUT), not 120. usage on
retrieval is read best-effort from persisted run state incl. USD cost
(read_run_usage), not always zero.
- building-a-tool.md: the [auth.example] oauth2_code recipe gains the
required token_response map (deny_unknown_fields rejects the example as
previously written); Gmail/Google Calendar corrected to first_party
runtimes (their manifests declare kind = "first_party"); the worked
api_key recipe is github's, not slack's; the tail "Quick implementation
checklist" and reference list were still v2-era (script lane,
assets/<extension>/ path, "manifest v2", v2.rs pointer) and now teach
the v3 shape; composition/CLI package-naming claim narrowed (the binary
does link slack/telegram adapter crates).
- contracts/extensions.md: legacy-format paragraph no longer claims
host-bundled packages ship v2 (none do), and origin_gate_matrix is
attributed to capability.rs + building-a-tool.md instead of
extension-runtime/overview.md §3, which does not mention it.
- how-to-port banner: `script` manifest authoring is retired; the
RuntimeKind::Script symbol survives as the process-sandbox lane's kind.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(contracts): repoint delivery_resolution.rs to its family directory
PR #7157 (merged to main 2026-08-07) cited
crates/ironclaw_outbound/src/delivery_resolution.rs in the
communication-delivery-resolution contract; the crate lives at
crates/domains/ironclaw_outbound/. Caught by this branch's docs surface of
check-guidance.py on the first merge of main after the gate landed —
exactly the drift class it exists for.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ci(check-guidance): harden the docs gate and fix review-surfaced doc drift
Applies the verified findings from the PR #7376 code review:
- The loop-exit and turn-runner contract docs claimed the deleted
loop_driver_host checkpoint-rejection test had 'moved into the
module'; it was deleted in #6696 and the fenced verification command
could not run. Both now cite the real surviving pins
(planned_driver.rs executor test + the ironclaw_turns projection
test mapped in scripts/reborn-e2e-rust.sh), with runnable commands.
- An unterminated comment now refuses at EOF like an unterminated
fence; before, one typo'd closer silently un-scanned the rest of the
file.
- Markdown links in the re-included corpora are now checked as repo
paths (they are never published, so the Mintlify-route rationale did
not apply); this alone added ~165 verified references.
- Each DOCS_REINCLUDED_PREFIXES entry must match at least one tracked
page or discovery refuses, so the planned docs/reborn consolidation
cannot silently drop the corpus from the scan.
- The living extension-runtime spec pages (overview.md,
standard-operations.md) and guidance-conventions.md join the scan;
guidance-conventions.md now describes the docs surface and the MDX
marker form, and its one dangling test path is repointed.
- Floors comment corrected (57 rule globs, not 38).
Also fixes four drifted claims from #7375's pages, verified against
live code: the interleaved function_call_output example was rejected
with 400 (resume input must be exclusively function_call_output items
with previous_response_id); model is echoed only on create (GET/cancel
report the 'reborn' placeholder); output_schema_ref is optional; and
the unknown-fields claim now names the two deliberate exemptions.
Self-tests: 43 pass (three new arms — unterminated comment refusal in
both syntaxes, re-included links as repo claims, stale re-included
prefix refusal).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ci(check-guidance): sync module docstring with re-included link checking
CodeRabbit caught the docstring still claiming the link extractor is
off for all of docs/** — stale since
|
||
|
Josh Ford
|
6dccbfbcbd |
docs: fix live drift in extension, responses API, and channel docs (doc-truth PR 1/5) (#7375)
* docs: fix live drift in extension, responses API, and channel docs The public tutorial taught the retired manifest v2 authoring format ([[host_api]] / [capability_provider.tools] / runtime_credentials), which the v3 parser hard-rejects, and never mentioned origin_gate_matrix; the Responses API page claimed temperature is rejected (accepted 0.0-2.0 and forwarded), claimed model must be "default" (any well-formed name <= 256 bytes), claimed max_output_tokens is rejected (accepted and ignored by DTO policy), and omitted the required model field from every request example; the channel tutorial pointed at two files that no longer exist. - docs/extensions/building-a-tool.md: rewrite manifest sections to the v3 [[tools]] / [[tools.credentials]] / [auth.<vendor>] shape, document origin_gate_matrix (origins, policies, ratchet), correct the hosted-MCP [mcp] section, packaging via ironclaw_extension_support package modules, and v3 test references; drop the nonexistent script runtime kind. - docs/api/responses.mdx: correct model/temperature/tools/tool_choice rejection rules, document unknown-field tolerance, add the required model field to all 15 request examples. - docs/channels/building-a-channel.mdx: replace dead crates/ironclaw_first_party_extensions + available_extensions.rs registration instructions with the current package-directory mechanism. - docs/reborn/contracts/extensions.md: state that production manifests author v3 (lowering into the v2 resolved model described there); label the v2 examples as legacy. - docs/reborn/how-to-port-tool-to-reborn.md: superseded banner pointing at the v3 guides. Part of #7317 (doc-truth pipeline, PR 1 of 5). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: address Copilot and CodeRabbit review on doc-drift PR - responses.mdx: tool_choice is rejected only without external-tools wiring; with external tools enabled it passes validation and is currently ignored (validate_responses_supported_fields_with_external_tools never checks it). - building-a-tool.md: clarify that effect-derived host ports are validation vocabulary against the HostPortCatalog allowlist; adapters are built by host-runtime services after authorization/obligations, never from manifests. - how-to-port-tool-to-reborn.md: mark the decision tree's RuntimeKind targets historical (v3 accepts only wasm|first_party; MCP is top-level [mcp]; process/CLI work is the sandbox lane). - building-a-channel.mdx: document the user install flow — virtual package root /system/extensions/<id>/manifest.toml, ironclaw extension search / install <extension-id> (ID, not path), WebUI Extensions lifecycle. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(responses): align the limits bullet with the corrected tool_choice claim The rejection list was corrected in the previous commit (tool_choice is rejected only without external-tools wiring); the "Limits and quirks" bullet still said "not supported ... rejected with 400". Same claim, one wording. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: apply verified code-review findings on the drift PR A full code review of this PR against live code surfaced claims the original drift pass got wrong or missed; every fix below was re-verified against the cited source before editing: - responses.mdx: standard `ironclaw serve` deployments always wire external tools (OpenAiCompatRouteMountPorts requires the store/resume pair; mount.rs wires them unconditionally), so `tools` is accepted and `tool_choice` is accepted-and-ignored on shipped binaries — the conditional 400s apply only to custom compositions without the wiring (now a Note). temperature is validated and carried in the submitted turn payload but not applied as a provider sampling parameter. Non-streaming wait timeout is 30 s (DEFAULT_RESPONSES_WAIT_TIMEOUT), not 120. usage on retrieval is read best-effort from persisted run state incl. USD cost (read_run_usage), not always zero. - building-a-tool.md: the [auth.example] oauth2_code recipe gains the required token_response map (deny_unknown_fields rejects the example as previously written); Gmail/Google Calendar corrected to first_party runtimes (their manifests declare kind = "first_party"); the worked api_key recipe is github's, not slack's; the tail "Quick implementation checklist" and reference list were still v2-era (script lane, assets/<extension>/ path, "manifest v2", v2.rs pointer) and now teach the v3 shape; composition/CLI package-naming claim narrowed (the binary does link slack/telegram adapter crates). - contracts/extensions.md: legacy-format paragraph no longer claims host-bundled packages ship v2 (none do), and origin_gate_matrix is attributed to capability.rs + building-a-tool.md instead of extension-runtime/overview.md §3, which does not mention it. - how-to-port banner: `script` manifest authoring is retired; the RuntimeKind::Script symbol survives as the process-sandbox lane's kind. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com> |
||
|
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
|
||
|
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. |