docs: agents overview drops gated actions and observe hook

[tonychang04]

Requirement (Tony's spec)

Remove the Gated actions and Observe hook bullets from agents/overview: those two are not available right now. Keep the four remaining initiatives (Agent setup, the insta skill, MCP server, one branch per task), keep the agent-setup mention, and state that all operations can be done by agents.

What changed

docs/agents/overview.mdx only:

• The Gated actions and Observe hook bullets are gone.
• The skill bullet drops "relay approval requests" (same feature the gated-actions bullet described).
• Frontmatter description drops "the governance model for agents" (twice flagged as stale in docs: drop governance from intro + nav, agents overview lists the initiatives #87 review) → "How agents connect: the insta skill and the MCP server."
• The closer is now: "Run insta setup agent once, and any operation on your projects, from provisioning a database to deploying compute, is one your agents can run. Mix CLI and MCP freely; both hit the same API." The "under the same governance" clause is gone with the bullets.

Deliberate wording notes for reviewers

• The "any operation ... is one your agents can run" universal is the required product positioning, requested verbatim ("mention all the operations can be done by agents"), and matches the accepted lead sentence's strength (see docs: tighten agents overview, lead with the agent-native claim #84 and docs: drop governance from intro + nav, agents overview lists the initiatives #87 review records; not newly discovered).
• Other pages still documenting gated actions/policies/observe (reference/gated-actions, reference/cli/overview#observe, governance/overview hidden route, mentions on branch-per-task, mcp-server, storage/overview) are out of scope here; this PR stops the overview from advertising them. Sweeping the remaining references is a recorded follow-up.
• No link on this page pointed at the removed bullets; the docs tree's only cross-page fragment link (#observe, added in docs: drop governance from intro + nav, agents overview lists the initiatives #87) leaves with the Observe bullet, resolving docs: drop governance from intro + nav, agents overview lists the initiatives #87's anchor-pinning follow-up by removal.

Review decisions (round 1, clean: all three verdicts approved, 0 Critical)

• Follow-up, recorded (r2d2 plan: local dashboard (Phase 6) from the product mock #1): repoint the two legacy redirects whose topics left this page — /agents/observe → /reference/cli/overview and /agents/human-in-the-loop → /reference/gated-actions. Correct catch that the redirect table was not in this body's out-of-scope list; bundled into the docs follow-up rather than a post-clean-round edit.
• Declined, deliberate (r2d2 feat: local dashboard (plan Phases 0/1/3) — instad-served React SPA #2): the closer's "any operation ... is one your agents can run" is the verbatim-required positioning; no scope qualifier. The tension with deploy/overview's gated-action note and branch-per-task's policy-first workflow is part of the recorded sweep decision below.
• Declined, deferred to owner (r2d2 fix(ci): lint excludes ui/; README explains the full start incl. dashboard #3): whether "not available right now" means hosted-only or ahead-of-launch is a product call; the repo's src/govern.ts defaults and the observe ingest endpoint are real, and the remaining docs pages still documenting gating/observe are an explicitly recorded follow-up sweep for the copy owner to direct.
• Follow-up, recorded (r2d2 docs: dashboard screenshot + per-page walkthrough in README #4): .insta/audit.jsonl and the hook trigger are now undocumented tree-wide; one line in the CLI reference's observe section restores it if the feature is meant to stay documented.

🤖 Generated with Claude Code

https://claude.ai/code/session_014qJQJw1ZJBUQHYQz4SKj7p

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
instacloud	🟢 Ready	View Preview	Sep 3, 2026, 10:27 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[cubic-dev-ai]

No issues found across 1 file

_{Re-trigger cubic}

[jwfing]

Summary
This docs-only PR removes the unshipped gated-actions and observe-hook positioning from the agents overview while preserving the requested agent setup, skill, MCP, branch-per-task, and all-operations messaging.

Requirements Context
I used the PR title/description as the primary requirement source, especially Tony's spec to remove only the agents/overview bullets for gated actions and observe hook, keep the four remaining initiatives, keep the insta setup agent mention, and state that all operations can be done by agents. I also checked the surrounding local docs and navigation; remaining gated-action references elsewhere are pre-existing and outside the PR's stated scope.

Findings

Critical
(none)

Suggestion
(none)

Information
(none)

Software engineering: no test coverage changes are needed for this prose-only MDX edit; I did not run the app test/lint/build scripts because there is no docs-specific check in package.json:9-14 and the review was read-only. Functionality: docs/agents/overview.mdx:1-13 matches the requested wording changes. Security: no security-relevant changes. Performance: no performance-relevant changes.

Verdict
Approved per the requested verdict rules: there are no Critical findings.

[jwfing]

Summary

Prose-only removal of the Gated actions and Observe hook bullets from docs/agents/overview.mdx; the spec's four requirements are all met, mechanics are clean, and my findings are about what the removal leaves stranded elsewhere in the tree and about the new closer's universal.

Two reviews already sit at 94cf4da (cubic-dev-ai "No issues found"; jwfing, 0 findings across all four dimensions). This is additive, not a retraction of either — I looked at the redirect table, tree-wide greps, and src/, which neither pass covered.

Requirements context

No /docs/superpowers/ in this repo. plans/ holds the same two dated design archives (2026-07-02-insta-oss-roadmap.md, 2026-07-06-local-dashboard.md); neither is a spec for this page, so I assessed against the PR body's quoted spec plus the linked-page tree. Requirement check against the body's four asks:

• Remove Gated actions + Observe hook bullets — done (docs/agents/overview.mdx:8-11 now four bullets).
• Keep the four remaining initiatives — Agent setup, insta skill, MCP server, one branch per task all present, links intact.
• Keep the agent-setup mention — :13 opens "Run insta setup agent once".
• State all operations can be done by agents — :13.

Findings

Critical

(none)

Suggestion

1. Two legacy redirect sources now land on a page with zero content on their topic (functionality)
docs/docs.json:225-227 redirects /agents/human-in-the-loop → /agents/overview, and :229-231 redirects /agents/observe → /agents/overview. The two bullets this PR deletes were that destination's only human-in-the-loop content and its only observe content. All 131 redirect destinations still resolve (no 404), but both reader paths are now topically dead — someone following a bookmarked /agents/observe lands on a page that never says "observe".

The body's out-of-scope list enumerates pages that still document these features; it doesn't mention the redirect table, so I don't read this as disclosed. Cheapest fix is repointing, not restoring text: /agents/observe → /reference/cli/overview (the insta observe install|report|sync section lives at docs/reference/cli/overview.mdx:302-308) and /agents/human-in-the-loop → /reference/gated-actions.

2. The new closer's universal contradicts the pages this page links to (functionality)
docs/agents/overview.mdx:13: "any operation on your projects, from provisioning a database to deploying compute, is one your agents can run."

• docs/deploy/overview.mdx:30: "Deploying is a gated action (deploy), so it can be put behind approval like anything else." The closer picked as its exemplar the one operation the tree names as gatable.
• Bullet 4's own target, docs/agents/branch-per-task.mdx:18-30, opens its workflow with policy: set project.delete, branch.delete, secrets.read to approve "once, before the first agent touches the project", and notes secrets.read approve "means the workflow's insta secrets step returns an approval to relay on every task".

Note the delta vs main is not just the added sentence — the base closer's "both hit the same API under the same governance" is what kept these compatible, and it left with the bullets. The universal phrasing itself is verbatim-required product positioning, so the fix is a scope qualifier on :13, not the sentence.

3. The "not available right now" premise doesn't hold for the product this docs tree ships inside (functionality)
CONTRIBUTING.md:78 makes docs/ the Mintlify source for docs.instacloud.com, but it ships in the insta-oss repo, and both removed features are live here:

• src/govern.ts:9-24 is a populated default policy table, with 'project.delete': 'approve' at :18 — gating is on by default on self-hosted insta-oss, matching docs/reference/gated-actions.mdx:60.
• src/server.ts:660: POST /projects/:id/events, commented "Agent event ingest (the CLI observe hook uploads credential-audit findings here)."

If "not available" means hosted-only, that's a fine product call — but then :13's universal is a hosted claim, and project.delete is precisely the operation an agent on the OSS build cannot run unattended. Worth a deliberate decision rather than leaving it implicit.

4. .insta/audit.jsonl is now undocumented tree-wide (software engineering / doc coverage)
grep -rn 'audit\.jsonl\|\.insta/observe' docs/ = 0 hits at head (it was 1 — this bullet). docs/reference/cli/overview.mdx:302-308 carries only the three commands, not the output path or the trigger ("linking a repo adds a credential audit on agent tool calls"). If the hook still writes that file, its location is no longer documented anywhere. One line in the CLI reference's observe section covers it.

Information

• The body's anchor claim verifies. At 94cf4da, grep -rno '](/[^)]*#[^)]*)' --include=*.mdx docs/ = 0 hits (was 1 at d2e555e) and grep -rn '^#\{1,6\}.*{#' --include=*.mdx docs/ = 0 pinned anchor IDs. The tree's only cross-page heading fragment did leave with the Observe bullet, so #87 r2's anchor-pinning follow-up is genuinely resolved by removal.
• /reference/gated-actions is not orphaned by this cut: five in-prose inbound links survive (docs/storage/overview.mdx:12, docs/projects/branches.mdx:56, docs/postgres/overview.mdx:35, docs/governance/overview.mdx:19, docs/deploy/overview.mdx:30) plus nav at docs/docs.json:120. The cost is discoverability from the agents page only. governance/overview remains nav-orphaned and de-indexed (carried from #87, where it was declined as deliberate — restating once, not re-escalating).
• Frontmatter :3 now names 2 of the page's 4 bullets. Mintlify uses description for meta, search and AI context, so "Agent setup" — the closer's headline command — and branch-per-task drop out of the page's own summary. Separately: this correctly retires the "governance model" description flagged twice in #87.
• The :6 lead-in universal is unchanged by this PR (not a delta), but the page now asserts the everything/any-operation claim twice with no governance qualifier left on it. Merged sibling 0d14707 (#83) walked back the mirror claim on the intro because "console-only flows exist … 'every operation' overclaims in either direction." Recorded, not a change request.
• Mechanics at 94cf4da, all green: docs.json parses; 16/16 nav pages resolve; 0 duplicate nav entries; 131 redirects, every destination resolves; 0 broken internal links; orphans exactly governance/overview + projects/branches (both pre-existing); git diff --check clean; 0 em/en dashes added; final newline present.
• No CI covers this. .github/workflows/ci.yml:14-20 is npm ci → typecheck → lint → test, all src/-scoped; docs/** has no gate, so nothing machine-checked the redirect and link facts above. Ninth consecutive ungated docs PR — a mint broken-links step would cover redirects, links and anchors.

Security: no security-relevant changes in this PR — no input handling, auth, secrets or dependencies touched. Performance: no performance-relevant changes — prose-only MDX, no new pages, assets or queries.

Verdict

approved — 0 Critical, 4 Suggestion, 6 Information. The spec's four requirements are met and the mechanics are clean; the suggestions are about the redirect table and the closer's scope, none of which block. (Informational: the explicit GitHub approval is a separate human action.)

[jwfing]

LGTM - approved.