Save this content to: AGENTS.md

# Agent instructions

## Purpose

This repository contains `jkudish/laravel-ai-librarium`, a Laravel-native research abstraction built on the official Laravel AI SDK.

## Sibling implementation

- The TypeScript sibling is [`jkudish/librarium`](https://github.com/jkudish/librarium), normally checked out locally at `../librarium`.
- Use the pinned `jkudish/librarium-spec` schemas, catalog and fixtures as the shared interchange authority. Do not copy the sibling's CLI, Node or private runtime architecture into this package.

## Architecture boundaries

- Use Laravel AI SDK primitives before adding custom AI integration code.
- Keep the core package free of application-owned persistence, Eloquent models, UI, and TypeScript runtime artifacts. Package-owned Run storage is approved: files, cache, memory, and query-builder database storage with one optional, publishable migration. Never run that migration automatically.
- TypeScript Librarium and this package share semantic interchange, not internal runtime architecture.
- Consumers own evidence policy, verification thresholds, conversation storage, and domain workflows.
- Built-in Run storage supports local Laravel disks (shared JS/PHP nonexpiring owner-checked marker), process-local ArrayStore, plain standalone uncompressed/unserialized Redis 7+ with native atomic CAS, query-builder database, and memory. Reject unsupported disks, Redis clusters, decorated/failover caches and native command retries; custom RunStores own other backends.
- Substantial optional SDKs or browser runtimes belong in separate adapter packages.
- Joey approved the simplified-surface SPEC.md on 2026-10-12 (PlanMode #4954): source selection, depth, max_cost, Run storage, and queue/find/refresh are authorized by that checkpoint. Follow the pinned jkudish/librarium-spec catalog, schemas, and fixtures. New policy APIs outside that spec still require approval; fallbacks are removed.

## Code conventions

- Use PHP 8.4+, Laravel 13, strict types, explicit parameter and return types, constructor property promotion, and readonly value objects where appropriate.
- Prefer native Laravel service providers, container bindings, facades, configuration, events, queues, and testing tools.
- Use `config()`, never `env()` outside configuration files.
- Use Pest for tests, Pint for formatting, and Larastan/PHPStan for static analysis.
- Do not commit `composer.lock` for this library.

## Verification

GitHub Actions are not this repository's verification authority. GitHub is the
collaboration/status surface; signoff is manual and non-enforced unless a future
separately authorized ruleset changes that policy.

```bash
composer test
composer analyse
composer format:check
composer validate --strict
LIBRARIUM_REDIS_TEST_PORT=<disposable-loopback-port> composer test:redis
composer pr:check
```

`composer pr:check` is the repository-owned exact-SHA Amp-orb gate. Run setup
separately, commit every intended change, require a clean worktree, and run the
check at the final candidate HEAD. It uses only the allowlisted offline package
plan and writes its exact-SHA, repository-, plan-, and runtime-bound mode-`0600`
receipt beneath Git administrative storage. A changed SHA, plan, repository,
PHP policy, actual runtime, or installed Composer-package set invalidates the
receipt. Never add install, live test, provider/network, publication, release,
deployment, database, Node, or application-owned steps to this plan without
separate authorization.

After the branch is pushed and an open PR points to the same exact head, a human
must separately approve the full lowercase SHA before running:

```bash
composer pr:signoff -- --approved-sha <full-lowercase-sha>
```

Use the canonical `basecamp/gh-signoff` extension. Keep `GH_SIGNOFF_TOKEN`
dedicated to this repository with Contents read, Pull requests read, and Commit
statuses read/write. Do not print or inspect the credential. Signoff reruns the
complete ordered `pr:check` plan after initial eligibility and token readiness,
then revalidates its replacement exact-SHA receipt before final drift guards.
Candidate checks and local Git subprocesses receive neither ambient GitHub
credentials nor the dedicated token. Only the pinned extension lookup,
read-only remote ref and PR checks, and final exact unforced signoff subprocess
map the dedicated token to `GH_TOKEN`; no call may fall back to ambient GitHub
credentials or saved CLI login. Signoff approval grants no merge, ruleset,
release, publish, deploy, production, database, or provider-call authority.

## Git workflow

- Work on feature branches, never directly on `main`.
- Commit coherent changes, run deep review, push, and open a PR.
- Never force-push, amend, or merge without explicit approval.