Statamic Toc Laravel Package

Product Decisions This Supports

• Self-serve configuration for non-developers. TOC defaults (field, first level, number of levels, last level, flat list) move from config/statamic-toc.php into the Control Panel under Settings → Addon Settings. This converts a developer/deploy task into an editorial-ops task and directly reduces "please change the TOC depth" tickets to engineering.
• Settings hierarchy / precedence model. Three layers now exist: config file defaults → CP defaults → per-tag overrides. This is a clean, explainable precedence chain that supports a "sensible default, escape hatch when needed" product posture rather than per-page configuration sprawl.
• Permissions and governance. The new manage toc settings permission is granted to nobody by default; the settings section is invisible until assigned to a role. This supports decisions about who owns content-presentation policy (typically a lead editor or site admin, not every author) and keeps the surface out of the way for teams that don't want it.
• Multi-brand / multi-site architecture. The feature is gated on goldnead/statamic-brand-context as a neighbour addon, with values stored per brand context. This is a signal that per-brand divergence in presentation is a first-class use case — relevant to roadmap decisions about multi-site rollouts and brand-level theming.
• Build vs. buy / extend vs. fork. The package absorbs a configuration-UI concern many teams would otherwise build themselves as a custom settings screen. It also demonstrates a composable addon pattern (optional neighbour addon registers settings; this addon merely participates), which is a reusable architectural decision for your own addons.
• Upgrade risk triage. The release notes explicitly flag that values saved under brand-context ≤ 1.12 may have been silently lost or misapplied. That is an actionable migration/QA decision for anyone who adopted early, and an argument for pinning the neighbour addon at ≥ 1.13 in your dependency policy.
• Platform-version roadmap. This addon still runs on Statamic 5, while the companion requires Statamic 6. That lets you adopt the settings UI only when you've completed a Statamic 6 upgrade — useful sequencing input if a framework upgrade is on the roadmap.

When to Consider This Package

Consider it when:

• You run a Statamic 5 or 6 site with long-form or documentation-style content where a table of contents is expected on most entries.
• Editorial or content-ops staff, not engineers, need to tune TOC behaviour (depth, which field, flat vs. nested) without a deploy.
• You already use goldnead/statamic-brand-context (≥ 1.13) or are planning a multi-brand / multi-site setup where per-brand presentation defaults matter.
• You want per-tag escape hatches — the release preserves individual overrides on the {{ toc }} tag, so a global default doesn't lock you in.
• You need role-scoped control over presentation settings for compliance or editorial-governance reasons.

Look elsewhere or defer when:

• You are not on Statamic (this is a Statamic addon, not a general Laravel package).
• You are on Statamic 5 and have no intention of adopting statamic-brand-context — the new screen simply will not register. Everything else still works via config/statamic-toc.php, so the value of this specific release is low for you; treat it as a no-op upgrade.
• You are running brand-context ≤ 1.12 and have already saved settings through it. Fix the neighbour addon version first, then re-verify stored values before relying on the UI; the notes describe a save that silently discarded a prior override.
• Your TOC needs are highly bespoke (custom markup, non-standard heading sources, per-entry manual curation). A configuration UI won't help; you likely need custom templating or a fork.
• You operate a strict "no optional companion addons" dependency policy — the screen is unusable without the neighbour, so you'd be carrying a code path you never exercise.

Adoption checklist: confirm Statamic version (5 vs. 6), confirm brand-context version ≥ 1.13 if you want the screen, plan the permission grant (nobody holds it initially — assign it to a role or the section will appear to be missing), and audit existing settings if you configured via brand-context before this release.

How to Pitch It (Stakeholders)

For executives: This release turns a developer-only configuration file into a permissioned settings screen in the admin panel. The business outcome is fewer engineering interrupts for presentation tweaks and faster content-ops iteration — a small, low-risk capability improvement rather than a new product line. It ships with no new required dependency: sites that don't install the companion addon behave exactly as before, and Statamic 5 support is retained. The only material risk is a narrow one, confined to teams who used the companion addon before version 1.13; those saved values should be re-checked after upgrading. There is no breaking change for existing installs.

For engineering: Precedence is now config file → CP defaults → per-tag override, with the CP screen registered by goldnead/statamic-brand-context ≥ 1.13 and no-op if absent. New permission manage toc settings is unassigned by default, so the section is invisible until explicitly granted — worth calling out in the release note to admins to avoid "the setting is missing" reports. Pin the neighbour addon at ≥ 1.13: earlier versions fail to write the last-registered addon's settings onto the config on single-brand installs, and up to 1.12 a second save could silently delete the first save's override. The companion addon requires Statamic 6 while this addon still supports Statamic 5, so the UI is effectively a post-Statamic-6-upgrade capability. Migration: no schema changes; verify stored settings on affected installs, then assign the permission.

Recommendation: Adopt on Statamic 6 sites already using brand-context (≥ 1.13) — clear win for editorial autonomy. On Statamic 5 or single-brand installs without the companion, upgrade is safe but inert; no urgency.