docs(hooks): document hooks.json storage path and migration

[factory-ain3sh]

Description

Documents the new hooks.json storage path that replaces the nested .factory/hooks/hooks.json location for Droid hook configuration. The hooks reference now declares ~/.factory/hooks.json and .factory/hooks.json as the canonical homes (with settings.json as a documented fallback); every hook cookbook ships copy-pasteable JSON in the canonical schema (events at the top level, no outer "hooks" wrapper); and the enterprise / power-user folder inventories list hooks.json alongside settings.json and mcp.json. Existing nested files keep working unchanged — the next save through /hooks writes hooks.json at the scope root and archives the legacy file as hooks/hooks.migrated.json.

Out of scope: plugin-local hook layout (hooks/hooks.json inside .factory-plugin/) — that path is unchanged by the runtime work and the plugin / reference docs already describe it correctly.

Related Issue

Closes CLI-688

Reviewer Guide

Read order: docs/reference/hooks-reference.mdx (canonical schema, fallback semantics, migration note) → docs/cli/configuration/hooks-guide.mdx (Quickstart step now points at hooks.json) → one cookbook (e.g. docs/guides/hooks/notifications.mdx) to verify the JSON unwrap pattern → docs/enterprise/hierarchical-settings-and-org-control.mdx + docs/guides/power-user/setup-checklist.mdx (folder inventory rows). JP files mirror their EN counterparts 1:1 — spot-check one to confirm parity.
Review depth: Standard. The only live design call is presenting the legacy settings.json location as a fallback rather than as a parallel authoring path; the JSON unwrap is mechanical (regex-driven) so the diff is large only because nesting collapses by one indent level.

Risk & Impact

These pages are user-facing config recipes — a wrong path or schema would silently steer pasted JSON to a file Droid no longer prefers. Risk is bounded by the runtime's own backward compatibility: settings.json and the nested hooks/hooks.json both still load, so any pre-update copy-paste continues to work; conversely the new canonical examples write to the same path the CLI itself persists to, so docs and runtime now agree. No code, schema, or CI changes.

Migration & Rollout

Order: docs publish as-is — no flag, no migration, no coordinated release. The corresponding runtime migration (canonical write + legacy archive) is already merged on the dev channel and ships to stable on the next CLI rollout.
User-facing migration story: existing .factory/hooks/hooks.json files keep loading; the first save through /hooks writes the new canonical file and archives the old one as hooks/hooks.migrated.json. The reference page documents this; no doc covers a manual migration path because none is required.
Rollback: revert this PR. The pre-update reference text was accurate against the prior CLI release and would not mislead users on older versions.

Verification

Behavior verified. Re-read every changed page; prose, JSON snippets, and the Note block in the reference page agree on path (hooks.json), fallback (settings.json), and migration target (hooks/hooks.migrated.json). Each cookbook example was checked against the canonical schema — events at the top level, the per-matcher inner hooks array preserved.
Regression coverage. rg 'hooks.*settings\.json' docs/ and rg '"hooks":\s*\{' docs/guides/hooks docs/jp/guides/hooks come back empty. The only surviving settings.json mention in the hook surface is the deliberate fallback note in hooks-reference.mdx; .vscode/settings.json in auto-formatting.mdx is an unrelated editor-config example.
Not tested. I did not render the JP pages under the docs theme — the substitution is structural and parallel to EN, so theme-side regression is unlikely.
Standard validators. No .mdx lint/test job in this repo; the Mintlify build runs on merge.

[mintlify]

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

Project	Status	Preview	Updated (UTC)
factory	🟢 Ready	View Preview	May 28, 2026, 4:12 AM

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

[factory-droid]

Droid finished @factory-ain3sh's task —— View job

---

Droid review complete.

The updated hooks.json paths and migration note look consistent within the touched pages, but several other hook guides still direct users to configure hooks via settings.json, which will conflict with the new canonical guidance.