Lin Codex Laravel Package

Product Decisions This Supports

• In-app help as a roadmap line item rather than a build project. The package ships the entire surface of a contextual help feature — a Livewire drawer, articles sourced from Markdown or the database, search, and translations — so a "cut first-week support tickets" or "improve activation on the billing screen" initiative can be scoped without scheduling a CMS, a search index, and an i18n effort as three separate epics.
• Build vs. buy, with a credible third option: adopt, pilot, keep the fork. The build estimate is weeks of engineering for a capability that is nobody's differentiator. MIT license, no per-seat cost, no vendor contract, small surface area — this is a reversible decision, which is the kind a PM can get approved quickly and unwind cheaply if it doesn't move the metric.
• Placement and timing as product questions you actually own. Contextual articles keyed to a screen or workflow turn "we need documentation" into a decision: which two or three high-friction screens get help in v1, and what triggers it — first visit, error state, repeated failed action. That's a product call, not an engineering one.
• Content ownership model, decided up front. Markdown-in-repo means help ships with the release that changes behavior, reviewed in the same PR, no admin UI to build or secure — but a typo costs a deploy. Database means an editorial workflow — but you now own seeding, backup, and the authoring surface, because the package does not document a real CMS. Most teams should launch on Markdown and migrate only when a named content owner exists and is blocked by deploy cadence. Structure article keys so that migration is mechanical.
• Instrumentation as a roadmap input. Drawer opens, searches, article opens, empty-search-result events are the funnel that answers "did this reduce tickets." Without them you'll be defending the line item on vibes at the next planning cycle.

When to Consider This Package

Consider it when: you're on Laravel 11.27.1+ / Livewire already, you have a small number of high-friction authenticated screens, your help content is short and stable, you can live with one mount point in your authenticated layout, and you're comfortable reading the source (it's small enough for an afternoon) and forking under MIT if the maintainer stops shipping.

Look elsewhere — or build the trivial version yourself — when:

• You need per-role, per-plan, or per-tenant scoping. It isn't there. Anything in the articles table is visible to anyone who can mount the component. If you have enterprise-only features or internal runbooks in your help corpus, you're writing the authorization layer yourself anyway, which erodes the "it's free" argument.
• You expect search at scale or across locales. Search is database-backed with no dedicated index, and locale-aware ranking is not a documented guarantee. Multi-locale results may mix languages. Before committing to thousands of articles × N locales, run a query-count and timing check on realistic seed data — this is the untested edge and the one most likely to degrade in production rather than staging.
• You need vendor support, SLAs, or an ecosystem to lean on. Zero stars, zero dependents, single-maintainer footprint, pre-1.0. There are no Stack Overflow answers when it breaks. This is a risk accepted, not a risk mitigated.
• You inherit an install on spatie/laravel-settings 3.7.0/3.7.1. An AI key saved through the settings page was written to settings.payload in plaintext. The fix requires publishing the new migrations and running migrate (encrypt_codex_ai_api_key encrypts in place and is idempotent). Treat this as a security ticket, not an upgrade chore, and cover local and staging — staging keys leak into screenshots and shared logs.
• You're on anything below Laravel 11.27.1. The documented failure mode is a silent security bug, not an error message. Pin finity-labs/lin-codex:0.4.4 and spatie/laravel-settings:^3.7.2 exactly and commit the lock file.

One further caution for the buy-side conversation: the package's own metadata is inconsistent. Its registry description describes config-driven "codex" reference data — statuses, categories, lookup values — which is not what the code does, and the install command appears as both fin-codex:install and codex:install across the README and changelog. Doc drift is normal for a young package, but it means onboarding cost is higher than the README implies, and you should budget a half-day of source reading before committing engineering time.

How to Pitch It (Stakeholders)

To executives: "We can ship contextual in-app help next sprint instead of next quarter. It's an MIT-licensed package that gives us the drawer, the articles, search, and translations for free — no vendor contract, no per-seat cost, no lock-in; if it stalls we fork it in a week. I'm proposing a two-screen pilot behind a feature flag with instrumentation, so we'll know within a month whether it's cutting support contacts before we invest in a content program. The risks are maturity (small maintainer, pre-1.0) and a recent encryption bug in its optional AI module — both manageable, both contained by pinning versions and not installing the AI piece."

To engineering: "Small, focused API that fits our stack — Livewire drawer mounted once in the authenticated layout, article keys derived from route names, Markdown files in the repo so content reviews happen in the same PR as the behavior change. Caveats you need to price in: pin exact versions (0.4.4 plus spatie/laravel-settings ^3.7.2), publish migrations before your first migrate or you'll miss the encrypt_codex_ai_api_key migration, install without --ai and keep the SDK key in config/ai.php so the secret never touches the database, and gate the component with our own policy because the package has no per-role or per-tenant scoping. It's roughly a day of integration plus an afternoon of source reading — cheap enough that a fork is a viable exit, and we should name now who owns that fork and under what trigger so the decision isn't made under pressure."