docs: remove gated actions, approvals, and observe from the docs site - #90
Conversation
Per Tony, these are not part of the product story right now. Deletes the gated-actions reference and the governance overview (nav entry too), strips every gating/approval/observe mention from the eleven pages that carried one, drops the policy/approvals/observe CLI sections and the MCP Governance tool table, trims the human-gate clause from the intro thesis and the site SEO description, and retargets the five redirects that pointed at the deleted governance page. All 131 redirect destinations still resolve; docs.json validates. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014qJQJw1ZJBUQHYQz4SKj7p
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
All reported issues were addressed across 13 files
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
jwfing
left a comment
jwfing
left a comment
There was a problem hiding this comment.
Summary
A clean, well-scoped docs-only removal of the gated-actions / approvals / observe story — the redirect and link work checks out in full, but the "entirely" in the requirement isn't met: two governance mentions survive, and one of them is now a dangling backreference to a sentence this PR deleted from the same file.
Reviewed at head ada90dcc923f25fc0fa29ebebba51ae998654662 (base b144a156, unchanged on refs/heads/main at review time).
Requirements context
No matching spec/plan found under /docs/superpowers/ — that directory does not exist in this repo. The repo keeps design docs under plans/ (2026-07-02-insta-oss-roadmap.md, 2026-07-06-local-dashboard.md), and neither is a spec for this docs change — both are dated design archives for the OSS runtime and dashboard, and both explicitly document governance as a shipped capability (plans/2026-07-02-insta-oss-roadmap.md:25, plans/2026-07-06-local-dashboard.md:76-80). So intent is assessed against the PR body ("Tony's spec") and its follow-through relationship to #89.
The operative requirement I'm holding this to is the body's own sentence: "remove them from the docs site entirely, not just from the agents overview."
What I independently verified (all green):
docs/docs.jsonparses as JSON; all 131 redirect destinations resolve to an on-disk.mdx; no redirect destination is itself a redirect source (no chains).- All 15 nav pages resolve on disk.
projects/branchesis nav-orphaned but was already orphaned onb144a156— not this PR. - Every internal
/...link acrossdocs/**/*.mdxresolves to a page or a redirect source — zero dangling links after the two page deletions. - No reference to
/reference/gated-actionsor/governance/overviewsurvives anywhere in the repo (not insrc/,ui/,README.md, orCOMPATIBILITY.md), so nothing outsidedocs/breaks. .github/workflows/ci.ymlrunstypecheck/lint/testonly; nothing in CI builds or validatesdocs/. The checks above are not gated anywhere — they were manual on this PR and will be manual on the next one.
Findings
Critical
Functionality — two governance mentions survive, contradicting both the requirement and the body's verification claim
The body asserts "zero remaining prose matches for gated/gating/approval/policy-set/observe/audit.jsonl/human-in-the-loop/governance across docs/**/*.mdx". That grep set is narrower than the concept: it misses the singular gate and the bare policy … gates phrasing. Two substantive mentions are still live at head:
-
docs/deploy/overview.mdx:42— "Restart lands configuration the way a deploy does, so it sits under the samedeploygate."This is the sharper of the two, because it's a dangling backreference introduced by this PR. "The same
deploygate" pointed back to the sentence this PR deletes twelve lines above it in the very same file (-Deploying is a [gated action](/reference/gated-actions) (\deploy`), so it can be put behind approval like anything else.`). With the antecedent gone, the surviving sentence refers to a gate the site never introduces — a reader has no way to resolve "the same … gate" to anything. Same file, same section pass; this one just wasn't caught. -
docs/quickstart.mdx:92— "You approve the sign-in and any action your project policy gates, and the agent drives the rest."quickstart.mdxis a top-level nav page and one of the highest-traffic pages on the site. It now tells a brand-new reader they'll be approving gated actions, while the concept, the command, and the reference table are all gone from the site.
Both need the same treatment the other nine pages got. Suggested minimal edits: drop the trailing clause at deploy/overview.mdx:42 after "no new spec." (the restart-vs-deploy point stands on its own without it); at quickstart.mdx:92, "You approve the sign-in, and the agent drives the rest."
I'm rating this Critical rather than Suggestion for two reasons: it's a direct miss against an explicit requirement ("entirely"), and #1 is not a leftover mention but incoherent prose created by this diff. It's a two-line fix.
Suggestion
Functionality — the two deleted routes get no redirect, while five untouched legacy paths do
docs/docs.json retargets /governance/api-tokens, /concepts/governance, /governance/approvals, /governance/login, /governance/organizations (docs/docs.json:170-173, 374-391), but adds no redirect for the two URLs this PR actually deletes: /reference/gated-actions and /governance/overview. The body calls the 404s out as a known decision, so this is a judgement call rather than an oversight — but the shape is odd: after this change five /governance/* sources redirect while /governance/overview itself hard-404s, and /reference/gated-actions was nav-listed and indexable ("indexing": "navigable"), so it is the one of the two most likely to have live inbound links and search results. Two more entries in the array — /reference/gated-actions → /reference/cli/overview and /governance/overview → /introduction — cost nothing and match the pattern the PR already applies.
Software engineering — the CLI page's "still ships these commands" softening wasn't applied to the two parallel MCP claims
docs/reference/cli/overview.mdx:6 correctly softens "Every command is listed below" → "Commands are listed below", precisely because the binary still ships policy / approvals / observe. The identical situation exists for the MCP surface after the Governance table is removed from docs/reference/mcp-tools.mdx:96-104, but both completeness claims there are untouched:
docs/reference/mcp-tools.mdx:3— frontmatterdescription: "Every insta_* tool the hosted MCP server exposes, grouped by area."This is also the page's SEO description.docs/agents/mcp-server.mdx:32— "The MCP tools reference tables the full set by area."
The <Note> at mcp-tools.mdx:9 ("the server's own tool listing is always current") partially hedges this, which is why it's a Suggestion and not a blocker — but the same softening the CLI page got would make it consistent.
Functionality — self-hosted project.delete defaults to approve, and the 202 flow is now undocumented anywhere
src/govern.ts:18 sets 'project.delete': 'approve' as the OSS default (the deleted docs/reference/gated-actions.mdx said so explicitly: "unlike the hosted platform, it ships with project.delete defaulting to approve"). docs/reference/cli/overview.mdx:100 still documents insta projects as "Create, list, link, and delete projects." So on a stock self-hosted install, the very first insta project delete returns an approval ID, and the docs site — after this PR — contains no explanation of what that ID is or that insta approvals approve <id> is the follow-up. /reference/cli/approvals (docs.json:508) redirects to a CLI overview that no longer has an approvals section, so that path dead-ends too.
The product-story call is the owner's and I'm not relitigating it. But this specific default makes the approval flow reachable out of the box rather than opt-in, so one line on docs/self-hosting/overview.mdx ("insta project delete requires an approval on self-hosted: run insta approvals list / insta approvals approve <id>") would keep a real, default-on behavior from being undiscoverable. Alternatively, flipping the OSS default to allow is the code-side answer — out of scope for a docs PR, but worth raising with the owner alongside this.
Software engineering — an editing artifact left a broken sentence
docs/agents/branch-per-task.mdx:18: "Per task, and the agent runs these itself if it has the insta skill:" — the "and" is a leftover from the removed "Then, per task — the agent runs these itself…" construction. Reads as a fragment. "Per task — the agent runs these itself if it has the insta skill:" restores it.
Functionality — "Why branches" now overclaims relative to the rewritten lead
docs/agents/branch-per-task.mdx:10 still says an agent sharing an environment "can corrupt data, race migrations, or read credentials it shouldn't. A branch removes the entire class of problem." Before this PR, the credential half of that claim was cashed out by the policy baseline (secrets.read approve, with the explicit note that credential reads accept --branch). With the baseline removed, the page's own lead at line 6 concedes that any --branch command "can still reach another branch", which line 10 then contradicts four lines later. The caveat does appear above the overclaim, which is why this isn't blocking — but "removes the entire class of problem" now overstates what a branch alone does for credential reads. Narrowing it to the data/migration half ("A branch removes the shared-environment class of problem: …") would keep it honest without reintroducing gating.
Information
- Security — no security-relevant code changes in this PR; it is docs-only, touches no auth, no input handling, no dependencies, and adds no new surface. The one security-adjacent effect is editorial: the site no longer carries the credential-gating guidance for agent access (the deleted
secrets.read approvebaseline), even thoughsrc/govern.tsstill enforces it. That's the intended product-story change per the requirement, noted rather than objected to. The--branchcross-branch-reach caveat is retained on bothbranch-per-task.mdx:6andprojects/branches.mdx:35, which is the part that mattered most to keep. - Performance — no performance surface in this PR (no code, no queries, no build-path change). Removing two pages marginally shrinks the built site.
- Test coverage — this repo has no test or CI surface over
docs/at all (.github/workflows/ci.ymlis typecheck/lint/vitest oversrc/; thetemplates-*.ymlworkflows arepaths:-filtered totemplates/). So there is no regression test to ask for here, and none of the verification in the PR body — JSON validity, nav resolution, 131 redirect destinations, dangling internal links — is enforced anywhere. This is the sixth docs PR in a row (#83, #84, #85, #87, #89, #90) doing that sweep by hand. A ~30-line node script underscripts/invoked from adocs-paths:-filtered workflow would make all four checks permanent and is, notably, the check that would have caught the Critical above if it also grepped for the removed vocabulary. Worth its own issue rather than this PR. docs/reference/cli/overview.mdx:252-258correctly retains theeventssection, so theinsta eventsreferences atbranch-per-task.mdx:42andmcp-tools.mdx:93still resolve. Good catch keeping the audit timeline while removing the gates.README.mdandCOMPATIBILITY.mdretaining governance is the right call and correctly reasoned in the body — I confirmed neither links a deleted docs page, so nothing breaks by leaving them.
Verdict
request_changes — one Critical: the removal is not complete, and docs/deploy/overview.mdx:42 is left referring to "the same deploy gate" whose defining sentence this PR deleted from the same file. Two lines of prose fix it. Everything else above is non-blocking; the redirect/link/nav work is genuinely thorough and I reproduced all 131 destination resolutions independently.
Fixes the Critical: the dangling 'same deploy gate' backreference in deploy/overview and quickstart's 'any action your project policy gates'. Also takes the round's suggestions: redirects for the two deleted routes, the MCP completeness claims softened to match the CLI page, the 'Per task, and' artifact, and branch-per-task no longer claims a branch alone solves credential reads. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014qJQJw1ZJBUQHYQz4SKj7p
jwfing
left a comment
jwfing
left a comment
There was a problem hiding this comment.
Summary
The PR removes several pages and nav entries, but it does not yet satisfy the docs-wide removal requirement.
Requirements Context
I used the PR #90 description/diff, the checked-out files, and the linked follow-up context from PR #89. The intent I reviewed against is: gated actions, approvals/human-in-the-loop, and observe should be removed from the docs site entirely, while repo-root README.md and COMPATIBILITY.md remain outside this docs-site scope by deliberate decision.
Findings
Critical
docs/quickstart.mdx:92,docs/deploy/overview.mdx:42,docs/postgres/overview.mdx:17— The docs site still exposes the gated-action/policy story. Quickstart says users approve actions their project policy gates, Deploy says restart sits under the samedeploygate, and Postgres says DSN reads are governed bysecrets.read. That directly misses the stated docs-wide removal requirement; the verification grep appears to have missedgate,gates, andgoverned.docs/reference/mcp-tools.mdx:3,docs/agents/mcp-server.mdx:32,COMPATIBILITY.md:45— The MCP docs still claim the reference lists “Every” / “the full set” ofinsta_*tools, but this PR intentionally removes the shipped policy/approval tools from that table. The CLI overview was correctly softened for the same reason; the MCP reference should be softened too or it remains inaccurate.
Suggestion
(none)
Information
- Software engineering:
docs/docs.jsonparses, configured nav pages exist, all 131 internal redirect destinations resolve to existing MDX pages, andgit diff --check main...HEADis clean. I did not run install-based CI because the review is read-only. - Security: no security-relevant code, dependency, auth, or data-flow changes.
- Performance: no runtime or performance-relevant changes.
Verdict
request_changes because the PR still violates the explicit docs-wide removal requirement.
…res overview) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014qJQJw1ZJBUQHYQz4SKj7p
jwfing
left a comment
jwfing
left a comment
There was a problem hiding this comment.
Summary
Round 2 at head 8277a46. My round-1 Critical (the dangling deploy gate backreference) is genuinely fixed, the removal sweep is now complete under an independently re-derived vocabulary, and every mechanical claim in the body checks out — no Critical findings remain.
Requirements context
This repo has no /docs/superpowers/; its spec/plan directory is plans/ at the repo root. I read both plans:
plans/2026-07-02-insta-oss-roadmap.md:25-26— governance (allow/deny/approve, 202 + approvalId, one-shot grants) and the observe-hook-compatible events ingest are recorded as shipped.plans/2026-07-06-local-dashboard.md:46,76-80— Phase 3 shipped an Approvals page and a policy matrix, and calls governance "the differentiator".
Those plans describe the insta-oss runtime, not the InstaCloud docs site this PR edits. The body's recorded scope decision — README.md / COMPATIBILITY.md keep documenting governance because they describe the codebase, which does ship it — is the right boundary and holds up. Intent otherwise taken from the PR body and the #89 follow-through.
Findings
Critical
(none) — my round-1 Critical is resolved. Verified at 8277a46:
docs/deploy/overview.mdx:42— the dangling "sits under the samedeploygate" backreference is cut; the redeploy bullet now ends at "no new image, no new spec."docs/quickstart.mdx:92— "any action your project policy gates" is cut; the surviving "You approve the sign-in" is OAuth browser sign-in, a genuinely different concept.
I re-derived the sweep vocabulary rather than reusing the body's list (that mismatch was the round-1 defect). Sweeping gate(s|d|way)?|gating|approv|polic(y|ies)|govern|observe|audit|human.in.the.loop|deny|denied|allowlist|permission|guardrail|sign.?off|consent|escalat|one-shot|irreversible|high.impact|blast radius|pending|202 over docs/**/*.mdx returns only the two OAuth approve hits and three audit hits for insta events (see Information). Nothing gating-related survives.
Suggestion
Functionality / security framing — docs/agents/branch-per-task.mdx:6, docs/projects/branches.mdx:35, docs/storage/overview.mdx:18
Across three pages the rewrite dropped the "the boundary is separation, not authorization" caveat along with the policy clause. Removing the mitigation is squarely in scope; removing the caveat is not — it's a factual statement about branch isolation that stands independently of gating. The replacement phrasing also shifts agency:
any command that accepts
--branchcan still reach another branch when you tell it to
In an agent-driven product the agent composes the command, so "when you tell it to" / "when you mean to" reads as though branch-crossing requires human intent. Nothing here is false — the trailing clause "the isolation comes from agents working on their own branch by default" does correctly convey convention-not-enforcement — which is why this is not blocking. Suggest restoring the three words "not authorization" and making the actor the agent, e.g. "…can reach another branch; the boundary is separation, not authorization."
Functionality — code path documented nowhere on the site
src/govern.ts:17 still ships 'project.delete': 'approve' as the self-hosted default, and src/server.ts:42-48 returns 202 {status:'approval_required', approvalId}. So a self-hosted user's first insta project delete parks on an approval the docs site now explains nowhere, and /reference/gated-actions redirects to a CLI overview with no approvals section.
I'm keeping this non-blocking, and lower than I had it in round 1, because the escape hatch is real and reachable: docs/self-hosting/overview.mdx:25 (plus four other pages) links COMPATIBILITY.md, which documents approvals list/approve/deny and "same 202 flow" at line 27. Your recorded decision — that the code-side fix is flipping the OSS default to allow, a product call outside a docs PR — is the correct read; this is just the note for whoever picks that up.
Information
auditsurvives by design, and correctly.docs/reference/mcp-tools.mdx:93,docs/reference/cli/overview.mdx:254,docs/agents/branch-per-task.mdx:42retain "the project's audit and agent-event timeline" forinsta events— a separately shipped feature (COMPATIBILITY.md:28, roadmap line 26), not a gating remnant. Worth noting only because the body's sweep summary doesn't mention the term. One residual wrinkle: that timeline still emitsgovern.pending/govern.approved/govern.denied(src/server.ts:47,268) which the site no longer explains — cosmetic, no action needed.projects/branchesis nav-orphaned but was already orphaned on base (git show b144a156:docs/docs.json→ 16 nav pages, noprojects/branches). Not introduced here.- No CI covers
docs/.ci.ymlisnpm ci→ typecheck → lint → vitest oversrc/; the threetemplates-*.ymlarepaths:-filtered totemplates/. Nothing insrc/,test/, orui/readsdocs.json, and the diff touches onlydocs/, so this change is inert to the gates — which is why I validated the docs by hand rather than relying on green checks.
Verification performed
Reproduced independently at 8277a46 (head re-confirmed via ls-remote immediately before posting):
docs.jsonparses as valid JSON.- 133 redirects — every destination resolves to an on-disk
.mdx; zero chained redirects (no destination is itself a source); no duplicate sources; no self-redirects. - All 15 nav pages resolve on disk.
- Zero dangling internal links across
docs/**/*.mdxafter the two page deletions. - No reference to
gated-actionsorgovernance/overviewanywhere in the repo except as intentional redirect sources. - Deletion seams read cleanly — no repeat of the round-1 "Per task, and the agent" artifact in
branch-per-task.mdx,skills.mdx, ormcp-server.mdx.
Software engineering: docs-only change, no test coverage applicable; the round-1 fixes landed as two focused commits (0730b64, 8277a46) with accurate messages. Security: no auth/authz code touched — the only security-relevant delta is the doc caveat softening noted above. Performance: no runtime code changed; not applicable.
Verdict
approved — zero Critical findings. Both Suggestions are non-blocking and the second is already deferred to the owner by your own recorded decision. Posted as a comment; the explicit GitHub approval is a separate human action.
jwfing
left a comment
jwfing
left a comment
There was a problem hiding this comment.
Summary
This docs-only sweep is nearly complete, but one gated-action vocabulary survivor remains in the published docs.
Requirements Context
I used the PR description as the primary spec: follow through on linked #89 by removing gated actions, approvals/human-in-the-loop, and observe from the docs site entirely. I also used CONTRIBUTING.md:78-78, which defines docs/ as the Mintlify source; the repo-root README/COMPATIBILITY governance content is intentionally outside this docs-site scope per the PR description.
Findings
Critical
docs/postgres/overview.mdx:34-34still saysservice.upgrade, which is the dotted gated-action/policy identifier style this PR is removing. The PR body specifically says the widened remnant grep coversservice.*action names and returns zero, but this line remains indocs/**/*.mdx. It also differs from the public command spelling used elsewhere, for exampleinsta services upgradeindocs/compute/overview.mdx:45-45. Replace it with user-facing wording likeservice upgradesorinsta services upgradeso the docs site no longer carries the removed gated-action vocabulary.
Suggestion
(none)
Information
(none)
Verdict
Request changes because there is one Critical finding. Software engineering: no code/test changes are involved; I used static read-only checks and did not run build/test commands that may write artifacts. Functionality: the sweep fails on the survivor above. Security: no security-relevant changes. Performance: no performance-relevant changes.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014qJQJw1ZJBUQHYQz4SKj7p
jwfing
left a comment
jwfing
left a comment
There was a problem hiding this comment.
Summary
This PR does the intended docs-site sweep, but two stale exhaustive-reference claims still need to be softened before merge.
Requirements Context
I reviewed this against the PR #90 description and the linked #89 context: #89 removed gated actions / observe only from the agents overview, while #90 explicitly expands that removal to the whole Mintlify docs site. I also checked the repo docs and planning files; the OSS README/COMPATIBILITY/plans still document governance/approvals/observe as runtime capabilities, which matches the PR's stated docs-site-only scope decision.
Findings
Critical
-
Functionality - stale completeness claims remain after removing documented commands/tools:
docs/reference/cli/overview.mdx:3-3,docs/quickstart.mdx:125-127docs/reference/cli/overview.mdxstill describes the page as a place to “find every command,” but this PR intentionally removes thepolicy,approvals, andobservecommand sections while noting the CLI still ships those commands. The Quickstart card likewise still says the MCP reference contains “Everyinsta_*tool,” even though the governance MCP tools were removed from that reference. These should get the same softening as the body copy, e.g. “find common commands” and “Theinsta_*tools...”.
Suggestion
(none)
Information
- Software engineering: this is a prose/config-only docs change. I did not run the repo test suite because the review is read-only and the configured tests are not docs-focused; I did run read-only checks for JSON parsing, nav page resolution, redirect destinations, redirect chains, missing internal MDX links, broad removed-vocabulary greps, and
git diff --check. - Functionality: aside from the Critical above, the deleted pages are out of nav, the added redirects resolve, and no deleted-page links remain in MDX.
- Security: no security-relevant code or dependency changes.
- Performance: no performance-relevant code paths changed.
Verdict
request_changes - one Critical finding remains, per the requested verdict rules.
The CLI page description and quickstart's MCP card both promised completeness the trimmed references no longer have. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014qJQJw1ZJBUQHYQz4SKj7p
jwfing
left a comment
jwfing
left a comment
There was a problem hiding this comment.
Summary
This docs-only PR cleanly removes the gated-actions, approvals, and observe story from the docs site without breaking live navigation or internal links.
Requirements Context
I reviewed against the PR description and the linked #89 follow-up context (#89), which called for a broader sweep after removing those topics from the agents overview. I also checked the local repo docs guidance in CONTRIBUTING.md:78-79: docs/ is the Mintlify source, navigation lives in docs/docs.json, and hidden pages still build if left on disk.
Findings
Critical
(none)
Suggestion
(none)
Information
- Software engineering: no issue. This is a prose/config-only docs change;
docs/docs.json:1-692parses as JSON,git diff --checkis clean, all 15 nav pages resolve, all 133 redirect destinations resolve, and there are no duplicate redirect sources. - Functionality: no issue. The removed pages have explicit redirects at
docs/docs.json:172-181, the old governance URL shapes are retargeted atdocs/docs.json:384-396, and live MDX no longer links to the deleted pages. - Security: no security-relevant changes; the PR removes docs prose and Mintlify config entries only.
- Performance: no performance-relevant changes; no runtime code, queries, request paths, or dependencies changed.
Verdict
Approved per the requested rule set: there are zero Critical findings.
jwfing
left a comment
jwfing
left a comment
There was a problem hiding this comment.
Summary
This docs-only sweep is ready from a code-review standpoint; I found no Critical issues.
Requirements context
I used the PR description for #90 and the linked #89 as the primary intent: #89 removed unavailable gated-actions and observe-hook positioning from the agents overview, while #90 expands that removal across the docs site. I also checked the repo guidance that docs/ is the Mintlify source and docs/docs.json owns navigation (CONTRIBUTING.md:76-79). Root README.md:34-38, COMPATIBILITY.md:26-28, and the planning docs still describe OSS governance/observe behavior, but the PR explicitly records those as out of docs-site scope, so I did not treat them as blockers.
Findings
Critical
(none)
Suggestion
(none)
Information
docs/docs.json:117-181,docs/docs.json:384-397: Static docs integrity checks passed: JSON parses, nav pages resolve, the deleted-page redirects point to existing pages, all 133 redirect destinations resolve, and there are no duplicate redirect sources or redirect chains.docs/quickstart.mdx:40-92: The only remainingapproveprose in MDX is OAuth sign-in approval, not the removed governance approval flow; broader grep found no remaining gated-actions/observe/human-in-the-loop/governance prose indocs/**/*.mdxoutside redirect source labels.docs/reference/cli/overview.mdx:1-6,docs/reference/mcp-tools.mdx:1-10: The CLI and MCP references now use softened completeness language after removing the hidden governance/observe sections..github/workflows/ci.yml:1-14: CI does not include a docs build/link checker, so verification here was manual static checking plusgit diff --check; I did not run the app test suite because this PR only changes docs.
Verdict
Approved per the requested verdict rules: there are no Critical findings. Software engineering checks are covered by JSON/nav/link validation and whitespace checks; functionality matches the stated docs-site removal; there are no security-relevant code or config changes; and there are no performance-relevant runtime changes.
2 participants
Requirement (Tony's spec)
Follow-through on #89: gated actions, approvals/human-in-the-loop, and the observe hook are not part of the product story right now, so remove them from the docs site entirely, not just from the agents overview.
What changed (13 files, +19/−166)
Deleted pages (and the one nav entry):
docs/reference/gated-actions.mdx(removed from the Reference nav group)docs/governance/overview.mdx(was already nav-hidden since docs: drop governance from intro + nav, agents overview lists the initiatives #87)Mentions stripped from every page that carried one:
introduction.mdx: the thesis loses "irreversible high-impact actions need a human gate"; three demands remain.agents/branch-per-task.mdx: the set-policy-first block, the gating baseline discussion, and the approval-relay step are gone; the page is now purely isolation + workflow + promote.agents/mcp-server.mdx: "Gated tools and approvals" section removed; the lead drops "approvals" and "under the same governance" (now "hitting the same API as the CLI").agents/skills.mdx: the approval-relay workflow bullet removed.reference/cli/overview.mdx:policy,approvals, andobservecommand sections removed; "Every command is listed below" softened to "Commands are listed below" since the CLI binary still ships those commands.reference/mcp-tools.mdx: the Governance tool table (policy_get, approvals_*) removed.deploy/overview.mdx,postgres/overview.mdx,storage/overview.mdx,projects/branches.mdx: the per-page gated-action / policy clauses removed.docs.jsonSEO description: "with one gated credential seam and humans in the approval loop" → "with credentials through one seam".Redirects (all 131 destinations verified resolving after the change):
/governance/api-tokens→/agents/mcp-server(tokens are documented there);/concepts/governance,/governance/approvals,/governance/login,/governance/organizations→/introduction./agents/observe,/agents/human-in-the-loop,/reference/cli/observekeep their existing live destinations.Deliberate decisions
README.mdandCOMPATIBILITY.mdstill document governance/approvals/observe. They describe the insta-oss codebase, which does ship these (src/govern.ts, the events ingest route), and neither links a deleted docs page. Changing the OSS product story is out of this docs-site scope and stays the owner's call.docs.jsonvalidated as JSON; nav pages all resolve on disk; zero remaining prose matches for gated/gating/approval/policy-set/observe/audit.jsonl/human-in-the-loop/governance acrossdocs/**/*.mdx.Review decisions (round 1: cubic P3 + two CHANGES_REQUESTED verdicts)
All Criticals fixed in
0730b64+8277a46; both stale CHANGES_REQUESTED reviews dismissed with pointers to the fixes:Taken (2nd verdict Critical):
postgres/overview.mdx's "Reading the DSN is governed bysecrets.read" removed in8277a46— the last survivor; the remnant grep now also coversgovernedand the policy action names (secrets.read,storage.*,service.*,db.restore,project.delete,branch.delete), and returns zero.The 2nd verdict's other Critical (MCP "Every" / "the full set" completeness claims) was already fixed in
0730b64; itsCOMPATIBILITY.mdcite falls under the recorded repo-root scope decision.Taken (r2d2 Critical): the two survivors the body's grep missed —
deploy/overview.mdx's dangling "the samedeploygate" backreference (incoherence this PR created) andquickstart.mdx's "any action your project policy gates". Both cut; the re-run grep now uses the wider vocabulary (gate/gates/gated/gating/approv/policy/policies/...) and the only remaining "approve" hits are quickstart's OAuth sign-in approval, a different concept.Taken (r2d2 suggestion): redirects added for the two deleted routes —
/reference/gated-actions→/reference/cli/overview,/governance/overview→/introduction. 133 redirects, all destinations verified resolving.Taken (r2d2 suggestion): the MCP completeness claims get the same softening as the CLI page —
mcp-tools.mdxdescription drops "Every",mcp-server.mdxdrops "the full set".Taken (cubic + r2d2): "Per task, and the agent" editing artifact fixed.
Taken (r2d2 suggestion):
branch-per-task.mdxno longer claims a branch removes credential-read risk; the claim is narrowed to the data/migration class.Declined, deferred to owner (r2d2 suggestion): documenting the self-hosted
project.deleteapproval flow onself-hosting/overviewwould reintroduce the approvals story this PR exists to remove. The real mismatch —src/govern.tsshipsproject.delete: 'approve'by default while the docs no longer explain the 202 flow — is flagged to the owner: the code-side answer is flipping the OSS default toallow, which is a product call outside this docs PR.Review decisions (round 2: one approved w/ 0 Critical, one CHANGES_REQUESTED w/ 1 Critical)
postgres/overview.mdx:34used the dotted action idservice.upgrade; replaced with the CLI spellinginsta services upgradeincd2271c. An exhaustive grep for any<noun>.<verb>action-id shape acrossdocs/**/*.mdxnow returns zero. Stale review dismissed with the pointer.project.delete: 'approve'default remains flagged to the owner (both reviewers now agree the code-side flip toallowis the real fix and out of scope here).Review decisions (round 3: 1 Critical)
reference/cli/overview.mdx's description ("find every command" → "find the common commands") and quickstart's MCP card ("Everyinsta_*tool" → "Theinsta_*tools") — softened inc5b86c7, completing the pattern applied to the page bodies in round 1. Stale review dismissed with the pointer.🤖 Generated with Claude Code
https://claude.ai/code/session_014qJQJw1ZJBUQHYQz4SKj7p