Nova Help Laravel Package

Product Decisions This Supports

• Whether internal admin tooling gets roadmap capacity at all. Nova is a back-office surface, and this package targets one specific failure mode: operators don't know what a field expects, what a status value means, or where the runbook lives. Embedding guidance directly above the field is the cheapest available fix. The real decision on the table is whether internal UX earns any capacity versus one more customer-facing feature.
• Support-load reduction as a measurable experiment. Contextual help at the point of data entry reduces "what do I put here?" interruptions to engineering and senior operators. If internal interruption load is a live concern, this is a low-cost trial with an observable outcome: count related questions in the four weeks before and after, on one resource.
• Build vs. buy vs. copy — and the answer here is usually copy. The capability is a display-only Nova field: no persistence, no business logic, roughly one class. MIT licensing makes copying legitimate. The build/buy question therefore collapses into "do we want a dependency for something we could own in an afternoon?"
• Standardizing a guidance layer as a team convention. Adopted as a pattern — every complex resource carries inline help for its two or three genuinely confusing fields — it becomes a platform decision rather than a one-off. That's the real product outcome: a norm about where operational knowledge lives.
• Documentation strategy. It moves a slice of documentation out of a wiki nobody opens and into the interface where the work actually happens. That's a signal about whether docs are treated as a product surface or an afterthought.
• Dependency-policy precedent. Approving a leaf-node, display-only, forkable package is low-stakes in isolation. The precedent it sets — "we tolerate pre-1.0, alpha-tagged packages from single-maintainer projects for cosmetic concerns" — is defensible, but it should be an explicit decision rather than a drift.

When to Consider This Package

Consider it when:

• You are running Laravel Nova 4 specifically. 0.6.0-alpha targets Nova 4 / Vue 3; 0.5.x is Nova 3 / Vue 2. They are not interchangeable, and pinning the exact version is mandatory — pre-1.0 plus an alpha tag means semver permits breaking changes at any time.
• The need is display-only guidance: explanatory text, formatting hints, links to runbooks or policy, warnings above a destructive field. No validation, no computed values, no data round-trip.
• You can accept an alpha-tagged dependency whose failure mode is cosmetic — a field that fails to render — rather than a broken workflow or data loss. A Vue 3 field on a Vue 2 host fails silently in the UI; that is the worst case.
• You want to validate the pattern cheaply before formalizing it: drop it into one messy resource, see whether operators actually read it, then decide whether to standardize.
• You need something this quarter and the alternative is a backlog item competing with customer-facing work.

Look elsewhere — or write the field yourself — when:

• You are not on Nova (Filament, a custom Blade admin, Retool). Nothing transfers.
• You are on Nova 5, or plan to upgrade soon. There is no published Nova 5 story, and the repository is archived with no release since May 2022. A Vue 3 field written against Nova 4 internals is exactly what a major bump invalidates. Budget for a fork at every Nova upgrade.
• You require maintained dependencies for compliance, security review, or a long-lived platform commitment. Archived status, 57 stars, zero dependents, and no release governance mean there is no escalation path beyond one contributor's GitHub notifications.
• You want to pin and forget. Every Nova major becomes a re-verification project.
• You need rich help experiences: expandable panels, modals, searchable docs, per-locale switching, or analytics on which help text gets opened. This is a thin text field, not a documentation system; extension points are deliberately minimal.
• Help copy must be authored by non-engineers. Text baked into PHP field definitions is not a content workflow. If a docs team owns the copy, you need a CMS or a database-backed source.

Practical recommendation: the archived status changes the calculus. On Nova 4, with a need this quarter and a small team, adopting 0.6.0-alpha pinned exactly is still defensible — but treat it as a reference implementation. Read src/Help.php (it is essentially one class; five minutes), copy it into app/Nova/Fields/Help.php, and drop the dependency. That keeps the UX win, removes the version treadmill, and costs less than the procurement conversation. On Nova 3, Nova 5, or any long-horizon commitment, reimplement rather than depend.

How to Pitch It (Stakeholders)

To executives: This is a small, free, MIT-licensed UI component for our internal admin panel. It places explanatory text and links to procedures directly beside the fields our operations team fills in, which cuts down on "what does this mean?" questions reaching engineering. Scope is deliberately narrow: it changes no data, adds no infrastructure, and carries no customer-facing risk. The relevant caveat is maintenance — the upstream project is archived with no release since 2022, so we should plan to own a copy of roughly one class of code rather than depend on it long-term. Net cost is measured in hours, not sprints; the expected return is fewer internal interruptions and fewer data-entry mistakes on the fields operators most often get wrong.

To engineering: This is a display-only Nova field — no persistence, no validation, no queries. It renders Markdown guidance above a form input and inherits the standard Nova visibility helpers (onlyOnForms(), canSee(), and so on). On Nova 4, pin 0.6.0-alpha exactly; on Nova 3 it's a different package line entirely. Because the repo is archived and Nova 5 will likely break it, the recommended move is to vendor the single class into app/Nova/Fields/Help.php and drop the dependency — we keep the UX, we own the upgrade path, and we avoid a pre-1.0 alpha from a dormant single-maintainer project sitting in our lockfile. Keep the copy in language files or a constants class, wrap it in __() from day one, and add a light test asserting the guidance fields exist on our key resources so copy doesn't silently vanish in a refactor.

To the operations team: Guidance text will start appearing directly above the fields people most often ask about — status values, money amounts, JSON payloads. It sits where the work happens instead of in a wiki. If a block isn't useful, tell us and we'll delete it; the whole value is proximity to the input, not the existence of the text.