Docara Laravel Package

Product Decisions This Supports

• Ship a documentation product, not a docs project. v3.7.0 closes the "last mile" gaps that usually become bespoke work: a real 404.html for static hosting, source-language marking for translated pages, and correct relative-asset resolution in example frames. These are the items that otherwise show up as a scoped side-project on a docs roadmap.
• Build vs. buy for the docs pipeline. The release reinforces that this package is a build system with verifiable output, not just a theme: verify-static, resolved-page-plans.json, _docara/page-metadata.json, sitemap.xml, and llms.txt are all artifacts a team can gate CI on. That makes "buy/adopt" defensible versus maintaining an in-house generator.
• Localization roadmap. Multilingual delivery is a first-class concern: per-locale content trees, one root 404 in the default locale, translations status --kind=page|lang (the previously ignored filter now works) for separating page translation debt from lang.json key debt, and translation_tracking.mode: "publish-current" for staging partially translated sites. The --kind fix is a small change with outsized planning value — it makes translation burndown reportable by workstream.
• Accessibility and internationalization as release criteria. Source-locale lang/dir on held-back pages and their outline entries, rem-based breakpoints that scale with browser text size, and reduced-motion handling for the hero effect are the kinds of fixes that turn "we care about a11y" into an auditable property. Useful if procurement, public-sector, or enterprise buyers ask.
• Hosting and deployment strategy. The docs now cover serving 404.html on nginx, Apache, and GitHub Pages. That supports standardizing on cheap static hosting/CDN instead of a Node runtime or a hosted docs SaaS, and it de-risks the "where does this run?" decision.
• Upgrade cadence decisions. No breaking changes here: deprecated utility names (border-bottom, surface-0) still render, and the build is byte-identical when not_found.enabled is false. That means the upgrade can ride a normal sprint rather than a migration project.
• Authoring model choice. Composition Recipe pages, declarative view utilities with an allow-list, and page-authoring contract validation let you decide how much author freedom vs. design-system conformance you want. The allow-list tightening (with recorded deprecated_utilities in the page plan) is a governance lever, not just a bug fix.

When to Consider This Package

Adopt when most of these hold:

• You are a PHP/Laravel shop and want docs authored in Markdown, built by an Artisan-driven toolchain, and deployed as static files.
• You need multiple locales with a defined default locale, per-locale lang.json overrides, and a translation-tracking story (publish source with a notice, or hold back).
• You want verifiable builds — page plans, static verification, metadata sidecars — so docs regressions fail CI rather than ship.
• You have (or want) a design-system-bundled theme and are comfortable with an allow-listed utility vocabulary for declarative layouts.
• You are standardizing on static hosting/CDN, including GitHub Pages, and want the shell to behave there.

Look elsewhere or scope extra work when:

• You are building a multi-product portal where a parent application owns the shell and error pages. This release hard-fails a portal build with PORTAL_NOT_FOUND_PAGE_FORBIDDEN if not_found.enabled: true — a correct guardrail, but it is a new build-stopping configuration state to design around.
• You need runtime/dynamic docs (auth-gated content, per-user rendering, docs-as-a-service search). This is a static generator; search here is a client-side script.
• You need editorial CMS workflows — the model is Git-based Markdown plus an advisory checklist (PAGE_EDITORIAL_REVIEW_REQUIRED), which the build now correctly reports as advisory rather than as an outstanding fix.
• You are not on PHP, or cannot take a dependency on the bundled framework/theme.

How to Pitch It (Stakeholders)

To executives: This release makes the documentation output production-complete without custom engineering: a proper branded 404 page for static hosts, correct language handling for translated pages, and accessibility fixes. It also makes the pipeline's quality signals trustworthy again — a validation bug that caused every build to warn and then stop checking subsequent pages is fixed, and the translations status report can now be filtered by kind so we can report page-translation progress separately from UI-string progress. Net effect: fewer bespoke docs tasks on the roadmap, and hosting on commodity static infrastructure. Upgrade risk is low: no breaking changes, and behavior is unchanged unless we opt into the new 404 page.

To engineering: v3.7.0 is a correctness release with one opt-out-able feature. Highlights: 404.html emitted at the deployment base, configurable via not_found.enabled and overridable with a root 404.md; it is noindex, excluded from hreflang, nav, backlinks, search index, sitemap, llms.txt, and page metadata, and listed in resolved-page-plans.json with "not_found": true — so our CI assertions on those artifacts stay valid. Portal builds now fail fast rather than silently diverging. Translation lang/dir now attribute source text correctly for screen readers. Breakpoints moved from px to rem with identical behavior at 16px default text size, and the JS breakpoint complement now matches the CSS query exactly. Declarative view utilities now map to real framework classes, with old names accepted and recorded as deprecated_utilities in the page plan — a clean deprecation path. Composition Recipe page validation now compiles the same placeholder as the build, so the spurious DOCUMENT_IR_INPUT_INVALID warning is gone and validation actually reaches every page. Also note the effects.* labels are now genuinely overridable in lang.json (the schema previously rejected them).

Ask: schedule the upgrade in a normal sprint, verify verify-static in CI after the bump, and decide deliberately whether to enable the 404 page per site (off by default for portals by design).