@zigrivers/scaffold 3.28.0 → 3.29.0

package/content/knowledge/web-app/web-app-rendering-strategies.md

@@ -2,6 +2,12 @@
 name: web-app-rendering-strategies
 description: SSR TTFB and SEO benefits, SSG for content sites, ISR, streaming SSR, React Server Components, and progressive hydration patterns
 topics: [web-app, rendering, ssr, ssg, isr, streaming, react-server-components, hydration]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://developer.mozilla.org/en-US/docs/Glossary/SSR
+  - url: https://developer.mozilla.org/en-US/docs/Glossary/SPA
 ---
 
 Rendering strategy is the foundational technical decision in a web app — it determines server infrastructure requirements, SEO characteristics, performance profile, and the developer model for data fetching. Understanding the precise mechanics of each strategy (not just their marketing descriptions) is essential for making and defending the right choice for a given project.

package/content/knowledge/web-app/web-app-requirements.md

@@ -2,6 +2,12 @@
 name: web-app-requirements
 description: SSR/SPA decision criteria, Core Web Vitals budgets, responsive breakpoints, browser support matrix, PWA considerations, and SEO requirements
 topics: [web-app, requirements, performance, pwa, seo, accessibility]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://www.w3.org/TR/WCAG22/
+  - url: https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps
 ---
 
 Defining web app requirements before writing a line of code prevents the most expensive rework in the project lifecycle. Rendering strategy, performance budgets, and browser support targets affect every architectural decision downstream. Locking these down early — with explicit tradeoff acknowledgment — removes ambiguity and gives the team a shared definition of "done."

package/content/knowledge/web-app/web-app-security.md

@@ -2,6 +2,14 @@
 name: web-app-security
 description: XSS prevention, Content Security Policy, CSRF tokens, clickjacking, Subresource Integrity, dependency auditing, and OWASP top 10 for web apps
 topics: [web-app, security, xss, csp, csrf, clickjacking, owasp, dependency-auditing]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://owasp.org/www-project-top-ten/
+  - url: https://www.w3.org/TR/CSP3/
+  - url: https://owasp.org/www-community/attacks/xss/
+  - url: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
 ---
 
 Web application security failures are among the most costly and common causes of data breaches. The OWASP Top 10 has catalogued the same categories of vulnerabilities for decades — not because they are new, but because they recur in every generation of frameworks and technologies. Understanding the attack vectors and their mitigations is not optional for engineers building user-facing web applications. Security must be designed in, not bolted on.

package/content/knowledge/web-app/web-app-session-patterns.md

@@ -2,6 +2,13 @@
 name: web-app-session-patterns
 description: Session management architecture, JWT vs cookie sessions, refresh token rotation, session storage, and hijacking prevention
 topics: [web-app, auth, sessions, jwt, cookies, security, redis]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://owasp.org/www-project-cheat-sheets/cheatsheets/Session_Management_Cheat_Sheet.html
+  - url: https://www.rfc-editor.org/rfc/rfc7519
+  - url: https://www.rfc-editor.org/rfc/rfc6265
 ---
 
 Session management is the mechanism by which a web application recognizes a returning user between HTTP requests. Because HTTP is stateless, sessions are an application-level construct — and the design decisions here directly affect security, scalability, and user experience. The wrong session architecture causes token theft, session fixation attacks, memory exhaustion on the server, and logout failures that leave users permanently authenticated even after they believe they've signed out.

package/content/knowledge/web-app/web-app-testing.md

@@ -2,6 +2,12 @@
 name: web-app-testing
 description: Component testing with Testing Library, SSR testing, E2E testing with Playwright, visual regression, accessibility testing with axe-core, and Lighthouse CI
 topics: [web-app, testing, playwright, testing-library, accessibility, visual-regression, lighthouse, e2e]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://www.w3.org/WAI/standards-guidelines/aria/
+  - url: https://developer.chrome.com/docs/lighthouse/overview
 ---
 
 Web application testing requires covering multiple distinct layers: component behavior, server rendering correctness, end-to-end user flows, visual appearance, accessibility compliance, and performance budgets. Each layer catches different classes of bugs and has different cost/value characteristics. The correct strategy invests heavily in component and integration tests (fast feedback, high coverage), uses E2E tests for critical user journeys (slow but comprehensive), and enforces visual and performance budgets in CI (catches regressions before users do).

package/content/knowledge/web-app/web-app-ux-patterns.md

@@ -2,6 +2,12 @@
 name: web-app-ux-patterns
 description: Responsive design, loading states, error boundaries, offline patterns, optimistic updates, and accessibility (WCAG) for web apps
 topics: [web-app, ux, responsive-design, loading-states, error-handling, accessibility, wcag, offline, optimistic-updates]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://www.w3.org/TR/WCAG22/
+  - url: https://developer.mozilla.org/en-US/docs/Web/Accessibility
 ---
 
 UX patterns are the difference between an app that users trust and one they abandon. The patterns covered here are not visual design choices — they are engineering decisions about how the app communicates state, handles failure, and responds to interaction. Implement them consistently across the entire app or they create a fragmented user experience that signals poor quality.

package/content/knowledge/web3/web3-access-control.md

@@ -2,6 +2,14 @@
 name: web3-access-control
 description: Role-based access control for smart contracts — Ownable2Step, OpenZeppelin AccessControl, Safe multisig as admin, TimelockController on dangerous ops, role separation, and decentralization via renouncing
 topics: [web3, access-control, openzeppelin, multisig, timelock]
+volatility: fast-moving
+last-reviewed: null
+version-pin: 'OpenZeppelin Contracts 5.x'
+sources:
+  - url: https://docs.openzeppelin.com/contracts/5.x/access-control
+    anchor: '#access-control'
+  - url: https://docs.safe.global/home/what-is-safe
+    anchor: '#safe-multisig'
 ---
 
 Most contract exploits are not novel cryptography — they are either missing access-control checks ("anyone can call `setFeeRecipient`") or a single admin key getting drained, phished, or coerced. Access control is the answer to three questions: who can change what, when can they change it, and whose consent is required to authorize the change. A protocol whose answer is "the deployer EOA, immediately, alone" is a protocol one phishing email away from a post-mortem. Production-grade access control replaces each of those answers with a deliberate engineering choice: granular roles, time-locked execution windows, and multi-party signing.

package/content/knowledge/web3/web3-architecture.md

@@ -2,6 +2,13 @@
 name: web3-architecture
 description: EVM smart-contract architecture decisions — modular vs monolithic decomposition, OpenZeppelin baseline, state minimization, library vs inheritance, diamond pattern caveats, and external-call discipline
 topics: [web3, architecture, solidity, evm, openzeppelin]
+volatility: evolving
+last-reviewed: null
+version-pin: 'OpenZeppelin Contracts 5.x; Solidity 0.8.x'
+sources:
+  - url: https://docs.openzeppelin.com/contracts/5.x/
+  - url: https://ethereum.org/en/developers/docs/smart-contracts/
+  - url: https://consensys.github.io/smart-contract-best-practices/
 ---
 
 This overlay targets **EVM** chains — Ethereum mainnet, the major L2s (Arbitrum, Optimism, Base, zkSync, Polygon zkEVM), and other EVM-compatible execution layers running Solidity 0.8.x bytecode. Non-EVM ecosystems (Solana / Anchor, Aptos and Sui / Move, Cosmos / CosmWasm) have fundamentally different storage, account, and execution models and are deliberately out of scope here; a future W3-2 overlay may cover dApp / frontend work and non-EVM runtimes. Architecture in this doc means the contract-side decisions a protocol lead makes before the first `forge build`: how to decompose, what to inherit, how state is laid out, and where the trust boundaries fall.

package/content/knowledge/web3/web3-audit-workflow.md

@@ -2,6 +2,13 @@
 name: web3-audit-workflow
 description: Pre-audit readiness, tooling (Slither, Echidna, Halmos, Certora), CI integration, firm selection, timing, remediation, and post-launch bug bounties for protocol teams preparing for a smart-contract audit
 topics: [web3, audit, slither, echidna, halmos, security]
+volatility: fast-moving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://consensys.github.io/smart-contract-best-practices/
+  - url: https://swcregistry.io/
+  - url: https://docs.openzeppelin.com/contracts/5.x/
 ---
 
 Audits are expensive ($30k–$500k+) and time-consuming, and the meter starts the day the auditors open your repo — not the day they find their first bug. A team that hands over a half-finished spec, 40% test coverage, and a Slither report full of unaddressed mediums is paying senior security engineers to do the work the team should have done before kickoff. The protocols that get the most out of an audit treat the engagement as a final review against work already proven correct, not as a substitute for it. Maximize value by being ready before the audit starts.

package/content/knowledge/web3/web3-common-vulnerabilities.md

@@ -2,6 +2,14 @@
 name: web3-common-vulnerabilities
 description: SWC-style checklist of the most-exploited Solidity bugs — reentrancy, delegatecall hazards, signature replay, front-running, unchecked calls, unbounded loops, and the small set of patterns that catch them
 topics: [web3, vulnerabilities, security, swc, solidity]
+volatility: fast-moving
+last-reviewed: null
+version-pin: 'SWC Registry'
+sources:
+  - url: https://swcregistry.io/
+    anchor: '#smart-contract-weakness-classification'
+  - url: https://consensys.github.io/smart-contract-best-practices/
+    anchor: '#known-attacks'
 ---
 
 The most-exploited contract bugs are usually the same handful, recycled across protocols by attackers who know exactly which patterns auditors and authors keep missing. Internalize this checklist; gate every PR with Slither and Foundry tests so the mechanical findings never reach review; require a dedicated reviewer pass for any change that touches the patterns below. Where this doc is the SWC-style enumeration of "what goes wrong," `web3-security.md` is the practices doc on "how to build so it doesn't" — read both, and treat `web3-audit-workflow.md` as the tooling glue.

package/content/knowledge/web3/web3-conventions.md

@@ -2,6 +2,12 @@
 name: web3-conventions
 description: Solidity style and convention discipline for smart-contract teams — forge fmt as single formatter, NatSpec on public functions, pinned pragma, custom errors over string reverts, naming and ordering rules
 topics: [web3, conventions, solidity, forge-fmt, natspec]
+volatility: stable
+last-reviewed: null
+version-pin: 'Solidity 0.8.x'
+sources:
+  - url: https://ethereum.org/en/developers/docs/smart-contracts/languages/
+  - url: https://consensys.github.io/smart-contract-best-practices/
 ---
 
 Solidity is brittle. The compiler is fast and unforgiving, the gas model rewards terseness, and the deployment surface is immutable — every style drift you tolerate during development eventually becomes a bytecode-determinism question, an audit comment, or a bug nobody can patch. The conventions below are the ones enforced by `forge fmt` and code review at every serious shop; encode them as CI gates and they stop being judgment calls.

package/content/knowledge/web3/web3-deployment-and-verification.md

@@ -2,6 +2,13 @@
 name: web3-deployment-and-verification
 description: Deploying smart contracts with forge script — broadcast artifacts as provenance, Etherscan verification, multi-chain flows, testnet rehearsals, mainnet pre-flight, post-deploy role hardening, and CREATE2 deterministic deploys
 topics: [web3, deployment, verification, forge-script, etherscan]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://ethereum.org/en/developers/docs/smart-contracts/deploying/
+  - url: https://docs.openzeppelin.com/contracts/5.x/
+  - url: https://docs.safe.global/
 ---
 
 Shipping a contract to mainnet is the most irreversible thing a smart-contract team ever does. There is no rollback, no patch deploy, no `kubectl rollout undo` — once the bytecode is live and users start interacting with it, you live with what you wrote. The instinct from web2 — "deploy fast, fix forward" — produces drained protocols on-chain. Treat deployment as a release event: every privileged operation scripted (not hand-called), every artifact archived (not transient), every step rehearsed on a testnet that mirrors mainnet, and every contract verified on Etherscan before you tell anyone the address. The cost of the discipline is half a day of process; the cost of skipping it is the entire protocol.

package/content/knowledge/web3/web3-dev-environment.md

@@ -2,6 +2,12 @@
 name: web3-dev-environment
 description: Reproducible local Foundry environment for smart-contract teams — pinned solc, pinned forge, anvil, forge-std, direnv, and CI parity
 topics: [web3, dev-environment, foundry, forge, anvil]
+volatility: evolving
+last-reviewed: null
+version-pin: 'Solidity 0.8.x'
+sources:
+  - url: https://ethereum.org/en/developers/docs/programming-languages/
+  - url: https://docs.openzeppelin.com/contracts/5.x/
 ---
 
 A reproducible Foundry environment is what lets every developer (and CI) get the same compile output, the same gas snapshots, and the same fork-test results. The pieces are not exotic: install Foundry through the official channel, pin the toolchain and the Solidity compiler, lean on `forge-std` for tests, push secrets out of your global shell with `direnv`, and mirror the same versions in CI. Skip any one of these and "works on my machine" creeps back in — usually as a gas-snapshot diff that nobody can reproduce.

package/content/knowledge/web3/web3-gas-optimization.md

@@ -2,6 +2,13 @@
 name: web3-gas-optimization
 description: Practical EVM gas optimization — measure first with forge snapshot, storage packing, unchecked loops, calldata vs memory, immutable, external-call discipline, and CI regression checks
 topics: [web3, gas-optimization, solidity, foundry]
+volatility: evolving
+last-reviewed: null
+version-pin: 'Solidity 0.8.x'
+sources:
+  - url: https://ethereum.org/en/developers/docs/gas/
+  - url: https://ethereum.org/en/developers/docs/evm/opcodes/
+  - url: https://consensys.github.io/smart-contract-best-practices/
 ---
 
 Gas matters because every operation a user pays for on Ethereum mainnet is real dollars, and on L2s the calldata you post to L1 is the dominant cost driver — both directions are visible in your users' wallets. But most "optimizations" save under 1% of a transaction's gas and cost clarity in exchange; that trade is rarely worth it. The point of this doc is to give you the small set of techniques that do pay for themselves, the discipline to measure before applying them, and the CI plumbing that catches regressions before they ship. If a section here ever recommends a change that obscures the code without producing a measurable saving, ignore it.

package/content/knowledge/web3/web3-oracles-and-external-data.md

@@ -2,6 +2,13 @@
 name: web3-oracles-and-external-data
 description: Oracle discipline for smart contracts — Chainlink price feeds with staleness/decimals/sign checks, TWAP for DEX prices, VRF for randomness, and fallback patterns that fail safe
 topics: [web3, oracles, chainlink, security]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://consensys.github.io/smart-contract-best-practices/
+  - url: https://swcregistry.io/
+  - url: https://ethereum.org/en/developers/docs/oracles/
 ---
 
 A smart contract is a deterministic state machine in a closed universe. The real world — ETH/USD, the weather in Lagos, the winner of last night's match, a genuinely random number — is none of those things. Oracles are the bridge between the two, and every bridge is a new attack surface with its own trust assumptions, latency, and failure modes. The job is not to remove the trust assumption (you cannot) but to make the bridge robust enough that an exploit costs more than the protocol holds. Most "oracle hacks" are not novel cryptography either — they are missed standard patterns: an unchecked staleness, a spot price used where a TWAP belonged, a `block.timestamp` standing in for entropy.

package/content/knowledge/web3/web3-project-structure.md

@@ -2,6 +2,12 @@
 name: web3-project-structure
 description: Opinionated Foundry project layout for smart-contract teams — src, test, script, lib, broadcast, foundry.toml, remappings — covering test naming, deploy provenance, and what belongs in git
 topics: [web3, project-structure, foundry, solidity]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://ethereum.org/en/developers/docs/smart-contracts/
+  - url: https://docs.openzeppelin.com/contracts/5.x/
 ---
 
 A smart-contract repository is read by more adversarial eyes than almost any other kind of codebase: auditors, MEV searchers, frontrunners, and the occasional regulator. Structure carries weight that goes beyond developer ergonomics. An auditor opening the repo for the first time should be able to find the contract under review, its tests, its deploy script, and its on-chain deployment receipts within thirty seconds. Gas snapshots and fuzz seeds need a fixed home so regressions are diffable. Broadcast logs are the audit trail tying a verified contract address back to a commit SHA — losing or muddling them turns "which version is mainnet running?" into a forensic exercise. Foundry's conventions answer most of these questions; this doc records the opinionated version a team should adopt before the first PR lands.

package/content/knowledge/web3/web3-requirements.md

@@ -2,6 +2,12 @@
 name: web3-requirements
 description: Problem framing, invariants, threat model, trust assumptions, and success metrics for shipping smart contracts and protocols to EVM chains
 topics: [web3, requirements, invariants, threat-model, security]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://consensys.github.io/smart-contract-best-practices/
+  - url: https://ethereum.org/en/developers/docs/smart-contracts/security/
 ---
 
 A smart contract shipped to an EVM chain without a written invariant set, a threat model, and an explicit list of trust assumptions is a guessing game with adversarial counterparties and irreversible state. This document defines the acceptance spec for a contract or protocol going to Ethereum mainnet, an L2 (Optimism, Arbitrum, Base), or a compatible sidechain. The audience is a senior Solidity engineer or protocol architect who can ship code but has not yet hardened it against funded adversaries. The goal is to force, in writing, the questions an auditor will ask on day one.

package/content/knowledge/web3/web3-security.md

@@ -2,6 +2,14 @@
 name: web3-security
 description: Layered security practices for smart contracts heading to mainnet — defense-in-depth, Checks-Effects-Interactions, pull payments, OpenZeppelin primitives, pause + multisig, and input validation discipline
 topics: [web3, security, solidity, openzeppelin, defense-in-depth]
+volatility: fast-moving
+last-reviewed: null
+version-pin: 'OpenZeppelin Contracts 5.x'
+sources:
+  - url: https://docs.openzeppelin.com/contracts/5.x/
+    anchor: '#security'
+  - url: https://consensys.github.io/smart-contract-best-practices/
+    anchor: '#general-philosophy'
 ---
 
 A smart contract is a public, immutable bank vault that anyone on the planet can call. The mempool is hostile, the bytecode is permanent, and the only patch deployment is a redeploy + migration that your users may or may not follow. Most exploits aren't novel cryptography — they're missed standard patterns: a state update after an external call, a `tx.origin` check that a phishing contract bypassed, a `transfer` to a contract that reverts and bricks an auction. Layered defense beats clever one-off mitigations, every time.

package/content/knowledge/web3/web3-testing.md

@@ -2,6 +2,12 @@
 name: web3-testing
 description: Testing discipline for Foundry smart contracts — unit, fuzz, invariant, and fork tests with coverage and gas snapshots wired into CI
 topics: [web3, testing, foundry, fuzz, invariants, fork-tests]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://consensys.github.io/smart-contract-best-practices/
+  - url: https://ethereum.org/en/developers/docs/smart-contracts/testing/
 ---
 
 Smart contracts must work the first time. Once deployed, a bug is a bounty for the next adversary who reads your storage layout, and "we'll patch it next sprint" is not an option when the only patch path is a migration to a brand-new address. Foundry's `forge test` runner makes property-level confidence cheap: unit tests pin known behavior, fuzz tests stress the boundaries you forgot, invariants assert the laws that must hold across every state sequence, and fork tests replay against real mainnet state. Use all four — none of them substitutes for any of the others.

package/content/knowledge/web3/web3-upgradeability.md

@@ -2,6 +2,13 @@
 name: web3-upgradeability
 description: Upgradeable contracts — when not to upgrade, UUPS vs Transparent vs Beacon, OpenZeppelin Upgrades with the Foundry plugin, storage gaps, ERC-7201, initializers, timelocked authorization
 topics: [web3, upgradeability, proxy, openzeppelin, storage]
+volatility: evolving
+last-reviewed: null
+version-pin: 'OpenZeppelin Contracts Upgradeable 5.x'
+sources:
+  - url: https://docs.openzeppelin.com/contracts/5.x/upgradeable
+  - url: https://docs.openzeppelin.com/contracts/5.x/api/proxy
+  - url: https://docs.safe.global/
 ---
 
 Upgradeable contracts trade simplicity for the ability to fix bugs after deployment. The cost is real: a new threat surface (the upgrade key itself), a class of storage-layout bugs that do not exist in immutable contracts, and a permanent dependency on whoever holds upgrade rights. An "upgradeable" protocol is one whose trust assumptions include a future action by an admin — every user of the protocol is implicitly trusting that admin to behave, in perpetuity. The honest default for most protocols is: do not upgrade unless you have to.

package/content/tools/knowledge-audit-entry.md

@@ -0,0 +1,79 @@
+---
+name: knowledge-audit-entry
+description: Audit one knowledge entry against its declared sources via grounded web retrieval
+category: tool
+stateless: true
+---
+
+# Knowledge Audit (Single Entry)
+
+You are auditing a single Scaffold knowledge entry against its declared authoritative sources. Your output is consumed by an automated pipeline — emit **only** the JSON object specified at the end.
+
+## Inputs
+
+- `{{entry_path}}` — absolute path to the knowledge entry being audited.
+- `{{entry_frontmatter}}` — parsed frontmatter object including `name`, `volatility`, `last-reviewed`, `version-pin`, `sources`.
+- `{{entry_body}}` — full body of the entry.
+- `{{prefetched_sources}}` — JSON array of `{url, body, hash, truncated}` objects. The Node-side audit runner has already fetched each declared source through an SSRF / DNS / redirect / timeout guard and embedded the response bodies here. **You have no web-fetch tool available — read these bodies instead.** A `truncated: true` flag means the body was capped at 96 KiB; do not infer anything is missing solely from that flag, but mention it in `preserve_warnings` if it materially limits your audit.
+
+## Procedure
+
+1. Read each entry in `{{prefetched_sources}}`. Each `body` is the current content of the corresponding source URL as of dispatch time. Treat these bodies as authoritative — they are what's live, regardless of what your training data says.
+2. Read the retrieved content carefully. Pay particular attention to:
+   - The current edition / version of any taxonomy or standard (compare against `version-pin`).
+   - Any normative statements in the entry body ("must", "should", "never") that the retrieved source contradicts or supersedes.
+   - New categories, sections, or recommendations in the source that the entry does not mention.
+3. Determine a verdict:
+   - `current` — sources confirm the entry, no findings.
+   - `minor-drift` — wording or examples slightly outdated; no substantive claims wrong.
+   - `major-drift` — substantive claims now inaccurate; structural revision needed.
+   - `superseded` — the source has shipped a new edition/version that changes the taxonomy; `version-pin` no longer applies.
+
+## CRITICAL: Grounding Rules
+
+- Where the prefetched source body contradicts the entry, **trust the prefetched body**.
+- Where the prefetched body contradicts your own prior knowledge, **trust the prefetched body**.
+- When you cannot verify a claim against any prefetched body, mark it `preserve_warnings` — do NOT mark it as drift, and do NOT invent corroboration.
+- Do not propose changes that introduce new normative claims unless those claims are verbatim or near-verbatim derivable from a prefetched body. Cite the source URL (from `{{prefetched_sources}}`) for every new normative claim.
+- Preserve the `## Summary` and `## Deep Guidance` headings exactly — the assembly engine depends on them.
+- You have NO tools available. Do not attempt to call WebFetch, Bash, Read, or any other tool. All evidence must come from `{{prefetched_sources}}` and the entry body.
+
+## Output (JSON only — no prose)
+
+```json
+{
+  "entry_name": "<from frontmatter>",
+  "audit_date": "<today's ISO date>",
+  "model": "<your model identifier>",
+  "verdict": "current | minor-drift | major-drift | superseded",
+  "sources_checked": [
+    {
+      "url": "<exact url from {{prefetched_sources}}>",
+      "retrieved_at": "<today's ISO date>",
+      "content_hash": "<exact hash from the matching {{prefetched_sources}} entry — do not recompute or invent>",
+      "summary": "<one sentence summary of what the source currently says>"
+    }
+  ],
+  "findings": [
+    {
+      "claim_in_entry": "<quoted snippet or paraphrase>",
+      "evidence_url": "<url>",
+      "evidence_date": "<ISO date>",
+      "source_excerpt": "<verbatim excerpt from retrieved source>",
+      "severity": "P0 | P1 | P2 | P3",
+      "drift_kind": "edition-upgrade | wording | new-category | obsolete-recommendation | factual-error"
+    }
+  ],
+  "proposed_changes": [
+    {
+      "location": "<exact existing top-level \"## \" heading line, e.g. \"## Deep Guidance\" or \"## OWASP Top 10\" — MUST be a verbatim H2 heading currently present in the entry. Phase 1 does not support targeting H3 or deeper subsections; if a change needs to land inside a subsection, replace or update the enclosing H2 section instead.>",
+      "kind": "replace | insert | delete",
+      "rationale": "<one sentence pointing at the finding(s) this resolves>",
+      "new_text": "<the proposed replacement or insertion text, with markdown link citations to retrieved sources. For `replace`, the new section's heading line (the same \"## \" heading) must be included as the first line. Omit this field for `delete`.>"
+    }
+  ],
+  "preserve_warnings": [
+    "<any claim you could not verify but should not change>"
+  ]
+}
+```

package/content/tools/review-code.md

@@ -1,7 +1,7 @@
 ---
 name: review-code
 description: Run all configured code review channels on local code before commit or push
-summary: "Review the current local delivery candidate with the three MMR CLI channels (Codex CLI, Gemini CLI, Claude CLI) plus the Superpowers code-reviewer agent as a complementary 4th channel reconciled into the same MMR job, before committing or pushing. Supports staged changes, an explicit ref range, or the full local delivery candidate (committed branch diff + staged + unstaged); untracked files are not included."
+summary: "Review the current local delivery candidate with the four built-in MMR CLI channels (Codex CLI, Gemini CLI, Claude CLI, Grok CLI) plus the Superpowers code-reviewer agent as a complementary agent channel reconciled into the same MMR job, before committing or pushing. Supports staged changes, an explicit ref range, or the full local delivery candidate (committed branch diff + staged + unstaged); untracked files are not included."
 phase: null
 order: null
 dependencies: []
@@ -15,19 +15,20 @@ argument-hint: "[--base <ref>] [--head <ref>] [--staged] [--report-only] [--fix-
 
 ## Purpose
 
-Run the same review stack used by `review-pr` (three MMR CLI channels plus
-the Superpowers code-reviewer agent as a complementary 4th channel), but on
-local code before commit or push. This is the preflight review entry point
+Run the same review stack used by `review-pr` (four built-in MMR CLI channels
+plus the Superpowers code-reviewer agent as a complementary agent channel), but
+on local code before commit or push. This is the preflight review entry point
 for bug fixes, small features, and quick tasks when the user wants
 multi-model review before anything leaves the machine.
 
-The three CLI channels are:
+The built-in CLI channels are:
 1. **Codex CLI** — implementation correctness, security, API contracts
 2. **Gemini CLI** — architectural patterns, broad-context reasoning
 3. **Claude CLI** — code quality, tests, and plan alignment
+4. **Grok CLI** — xAI's independent second opinion (correctness, code quality; proprietary)
 
-Plus the 4th channel:
-4. **Superpowers code-reviewer** — agent-based review dispatched via the
+Plus the complementary agent channel:
+5. **Superpowers code-reviewer** — agent-based review dispatched via the
    `superpowers:code-reviewer` skill, reconciled into the same MMR job via
    `mmr reconcile` for a unified verdict.
 
@@ -53,7 +54,7 @@ brand-new files.
 
 ## Expected Outputs
 
-- A reconciled four-channel review summary for the local delivery candidate (three MMR CLI channels + Superpowers code-reviewer)
+- A reconciled multi-channel review summary for the local delivery candidate (four built-in MMR CLI channels + Superpowers code-reviewer)
 - One of these verdicts: `pass`, `degraded-pass`, `blocked`, `needs-user-decision`
 - Fixed code when findings are resolved in normal mode
 
@@ -257,11 +258,11 @@ Format the changed-file context like:
 [full file contents]
 ```
 
-### Step 4: Run All Three Review Channels
+### Step 4: Run All Built-in Review Channels
 
 Each channel reviews independently. Do NOT share one channel's output with another.
 
-**Foreground only:** Always run Codex and Gemini CLI commands as foreground Bash calls. Never use `run_in_background`, `&`, or `nohup`. Background execution produces empty output. Multiple foreground calls in a single message are fine.
+**Foreground only:** Always run Codex, Gemini, and Grok CLI commands as foreground Bash calls. Never use `run_in_background`, `&`, or `nohup`. Background execution produces empty output. Multiple foreground calls in a single message are fine.
 
 #### Channel 1: Codex CLI
 
@@ -325,6 +326,31 @@ Dispatch via `claude -p` with the review prompt.
 This channel must review the same local delivery candidate, even when no PR or
 clean ref range exists.
 
+#### Channel 4: Grok CLI
+
+Check installation and auth:
+
+```bash
+command -v grok >/dev/null 2>&1
+grok models >/dev/null 2>&1
+```
+
+- If `grok` is not installed: skip this channel and record root-cause `not_installed`
+- If auth fails: tell the user to run `! grok login`, retry after recovery, and if recovery is not possible, record root-cause `auth_failed` and continue with the remaining channels
+
+If auth cannot be recovered, or if Grok is not installed, queue a compensating Claude self-review pass focused on an independent second opinion over correctness and code quality. Label findings as `[compensating: Grok-equivalent]`.
+
+Grok ignores stdin — pass the prompt via a file, and unwrap the reply from `.text`:
+
+```bash
+PROMPT_FILE=$(mktemp)
+# ...write the full review prompt to "$PROMPT_FILE"...
+grok --prompt-file "$PROMPT_FILE" --output-format json 2>/dev/null
+rm -f "$PROMPT_FILE"   # clean up the temp prompt file
+```
+
+If the CLI exits with a non-zero code, produces malformed/unparseable output, or is killed by the tool runner timeout, record root-cause `failed` and queue a compensating pass for that channel.
+
 **After all channels:** Run any queued compensating passes as foreground Claude self-review passes. Each compensating pass uses the same review prompt as the missing channel, focusing on that channel's strength area.
 
 ### Step 5: Use This Review Prompt
@@ -768,8 +794,9 @@ Output a concise summary in this format:
 ### Channels Executed
 - Codex CLI — root cause: [completed / not_installed / auth_failed / timeout / failed], coverage: [full / compensating (Codex-equivalent)]
 - Gemini CLI — root cause: [completed / not_installed / auth_failed / timeout / failed], coverage: [full / compensating (Gemini-equivalent)]
-- Claude CLI — root cause: [completed / not_installed / auth_failed / timeout / failed], coverage: [full / none (Claude is never compensated — it IS the compensator for Codex/Gemini)]
-- Agent review (Superpowers code-reviewer, 4th channel) — [completed / skipped], injected via `mmr reconcile`
+- Claude CLI — root cause: [completed / not_installed / auth_failed / timeout / failed], coverage: [full / none (Claude is never compensated — it IS the compensator for Codex/Gemini/Grok)]
+- Grok CLI — root cause: [completed / not_installed / auth_failed / timeout / failed], coverage: [full / compensating (Grok-equivalent)]
+- Agent review (Superpowers code-reviewer, agent channel) — [completed / skipped], injected via `mmr reconcile`
 
 ### Findings
 [consensus findings first, then single-source findings]
@@ -783,8 +810,8 @@ for the next delivery step (commit, push, or PR creation).
 
 ## Process Rules
 
-1. **Foreground only** — Always run Codex and Gemini CLI commands as foreground Bash calls. Never use `run_in_background`, `&`, or `nohup`.
-2. **All 3 channels are mandatory** — skip only when a tool is genuinely not installed, never by choice.
+1. **Foreground only** — Always run Codex, Gemini, and Grok CLI commands as foreground Bash calls. Never use `run_in_background`, `&`, or `nohup`.
+2. **All built-in CLI channels are mandatory** — skip only when a tool is genuinely not installed, never by choice.
 3. **Auth failures are not silent** — always surface to the user with recovery instructions.
 4. **Independence** — never share one channel's output with another.
 5. **Fix before proceeding** — findings at or above `fix_threshold` must be resolved before moving to the next task.

package/content/tools/review-pr.md

@@ -14,11 +14,11 @@ argument-hint: "<PR# or blank> [--fix-threshold P0|P1|P2|P3]"
 
 ## Purpose
 
-Run the three CLI review channels (Codex, Gemini, Claude) on a pull request
-**plus** the Superpowers code-reviewer agent as a complementary 4th channel,
-and reconcile all findings through MMR. This is the single entry point for
-**PR-scoped** code review — agents call this once instead of remembering four
-separate review invocations.
+Run the four built-in CLI review channels (Codex, Gemini, Claude, Grok) on a
+pull request **plus** the Superpowers code-reviewer agent as a complementary
+agent channel, and reconcile all findings through MMR. This is the single entry
+point for **PR-scoped** code review — agents call this once instead of
+remembering separate review invocations.
 
 **For non-PR targets**, don't use this tool. Call `mmr review` directly with
 the appropriate input mode, or use `scaffold run review-code` for local
@@ -34,13 +34,14 @@ pre-commit review:
   under `set -o pipefail`)
 
 The `--diff` flag expects diff-format content; it does not read raw document
-content. The three-channel review itself is not PR-specific — this tool is
+content. The built-in CLI review itself is not PR-specific — this tool is
 just the PR wrapper around the more general `mmr review` CLI.
 
-The three channels are:
+The built-in CLI channels are:
 1. **Codex CLI** — OpenAI's code analysis (implementation correctness, security, API contracts)
 2. **Gemini CLI** — Google's design reasoning (architectural patterns, broad context)
 3. **Claude CLI** — Anthropic's code review (plan alignment, code quality, testing)
+4. **Grok CLI** — xAI's independent second opinion (correctness, code quality; proprietary)
 
 ## Inputs
 
@@ -53,7 +54,7 @@ in the review criteria config rather than read at dispatch time.
 
 ## Expected Outputs
 
-- All three CLI review channels executed (or fallback documented) plus the Superpowers code-reviewer 4th channel reconciled via `mmr reconcile`
+- All built-in CLI review channels executed (or fallback documented) plus the Superpowers code-reviewer agent channel reconciled via `mmr reconcile`
 - findings at or above the configured `fix_threshold` fixed before proceeding (read from `results.fix_threshold` in the verdict JSON; default `P2`)
 - Review summary with per-channel results and reconciliation
 
@@ -108,7 +109,7 @@ The CLI supports multiple input modes:
 
 **Manual fallback** (when MMR CLI is not installed):
 
-Run Codex, Gemini, and Claude CLI commands individually as foreground Bash calls.
+Run Codex, Gemini, Claude, and Grok CLI commands individually as foreground Bash calls.
 Never use `run_in_background`, `&`, or `nohup`.
 
 #### Channel 1: Codex CLI
@@ -141,11 +142,28 @@ claude -p "REVIEW_PROMPT" --output-format json 2>/dev/null
 
 Claude CLI handles its own auth. Focus: plan alignment, code quality, testing.
 
+#### Channel 4: Grok CLI
+
+```bash
+command -v grok >/dev/null 2>&1 || echo "Grok not installed"
+grok models >/dev/null 2>&1 && echo "Grok authed" || echo "Run: grok login"
+# grok ignores stdin — the prompt MUST be passed via a file (or the -p arg).
+# Use mktemp (never a predictable /tmp path) and clean up afterward:
+PROMPT_FILE=$(mktemp)
+printf '%s' "REVIEW_PROMPT" > "$PROMPT_FILE"
+grok --prompt-file "$PROMPT_FILE" --output-format json 2>/dev/null
+rm -f "$PROMPT_FILE"
+```
+
+Grok's JSON wraps the reply in `.text`. If not installed or auth fails, queue a
+compensating pass focused on an independent second opinion over correctness and code
+quality. Auth failure recovery: `! grok login`.
+
 **After all channels:** Run any queued compensating passes as additional `claude -p`
-dispatches with focused prompts. Label findings as `[compensating: Codex-equivalent]`
-or `[compensating: Gemini-equivalent]`.
+dispatches with focused prompts. Label findings as `[compensating: Codex-equivalent]`,
+`[compensating: Gemini-equivalent]`, or `[compensating: Grok-equivalent]`.
 
-### Step 3: Run Agent Code Review (4th channel)
+### Step 3: Run Agent Code Review (complementary agent channel)
 
 Dispatch your platform's code-reviewer skill for a complementary review:
 - **Claude Code:** dispatch `superpowers:code-reviewer` subagent with the PR diff and review criteria
@@ -614,8 +632,8 @@ In either path, output the message and stop. Do NOT proceed to the next task wit
 
 ## Process Rules
 
-1. **Foreground only** — Always run Codex, Gemini, and Claude CLI commands as foreground Bash calls. Never use `run_in_background`, `&`, or `nohup`.
-2. **All three CLI channels are mandatory** — Codex CLI, Gemini CLI, and Claude CLI. Plus the Superpowers code-reviewer agent as a complementary 4th channel reconciled via `mmr reconcile` (Step 3). Skip a CLI channel only when a tool is genuinely not installed or auth cannot be recovered (in which case MMR emits a compensating pass for missing Codex/Gemini channels; a missing Claude CLI has no compensator). Never skip by choice.
+1. **Foreground only** — Always run Codex, Gemini, Claude, and Grok CLI commands as foreground Bash calls. Never use `run_in_background`, `&`, or `nohup`.
+2. **All built-in CLI channels are mandatory** — Codex CLI, Gemini CLI, Claude CLI, and Grok CLI. Plus the Superpowers code-reviewer agent as a complementary agent channel reconciled via `mmr reconcile` (Step 3). Skip a CLI channel only when a tool is genuinely not installed or auth cannot be recovered (in which case MMR emits a compensating pass for missing Codex/Gemini/Grok channels; a missing Claude CLI has no compensator). Never skip by choice.
 3. **Auth failures are not silent** — always surface to the user with the exact recovery command.
 4. **Independence** — never share one channel's output with another. Each reviews the diff independently.
 5. **Fix before proceeding** — findings at or above `fix_threshold` must be resolved before moving to the next task.

package/dist/cli/commands/dashboard.d.ts

@@ -6,7 +6,7 @@ interface DashboardArgs {
     root?: string;
     force?: boolean;
     output?: string;
-    'no-open'?: boolean;
+    open?: boolean;
     'json-only'?: boolean;
     service?: string;
 }

package/dist/cli/commands/dashboard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dashboard.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/dashboard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAgC1C,UAAU,aAAa;IACrB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAkCD,QAAA,MAAM,gBAAgB,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,CAkO3E,CAAA;AAED,eAAe,gBAAgB,CAAA"}
+{"version":3,"file":"dashboard.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/dashboard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAgC1C,UAAU,aAAa;IACrB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAiCD,QAAA,MAAM,gBAAgB,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,CAkO3E,CAAA;AAED,eAAe,gBAAgB,CAAA"}