# Externa

> Documentation for Externa — open-source headless CMS for Laravel. Documented core version: **1.2.0**. Docs site: https://docs.externa.qiick.io

This file lists every public docs page as Markdown. Full corpus: https://docs.externa.qiick.io/llms-full.txt

## Getting started

- [Introduction](https://docs.externa.qiick.io/index.md): Externa is a Laravel 13 + Inertia/React 19 admin for dynamic collections, hierarchical files, Spatie RBAC, and an in-app AI assistant.
- [Quick Start](https://docs.externa.qiick.io/docs/quick-start.md): Copy-paste Herd .env, seed roles, and minimal commands to run externa-core locally.
- [Installation](https://docs.externa.qiick.io/docs/installation.md): Install externa-core locally with Laravel Herd, Composer setup, seeding, queue workers, and optional AI gateway configuration.
- [Headless starter](https://docs.externa.qiick.io/docs/headless-starter.md): Official minimal Next.js and Nuxt starters against Externa Public CMS API — list + detail, env config, no marketing theme.
- [Packagist & create-project](https://docs.externa.qiick.io/docs/packagist.md): Install Externa with composer create-project from Packagist; human path uses externa:install; CI keeps composer setup separate.
- [Supported databases](https://docs.externa.qiick.io/docs/supported-databases.md): Official Externa database matrix — SQLite, PostgreSQL, MySQL 8+, MariaDB 10.6+ — with charset notes and CI coverage.
- [Project layout](https://docs.externa.qiick.io/docs/project-layout.md): Directory map of externa-core — routes, controllers, models, services, AI tools, React pages, Wayfinder, and tests.
- [Environment variables](https://docs.externa.qiick.io/docs/environment-variables.md): Full externa-core environment variable reference for app, database, queue, mail, files, AI, seeding, and activity log settings.
- [Using with AI coding tools](https://docs.externa.qiick.io/docs/ai-coding-tools.md): Point Cursor, Claude Code, and VS Code at Externa docs via Context7, llms.txt, and the in-browser Ask the docs button.

## Concepts

- [Architecture](https://docs.externa.qiick.io/docs/architecture.md): How externa-core is structured as a Laravel + Inertia SPA with domain modules, services, jobs, and shared page props.
- [Effective permissions](https://docs.externa.qiick.io/docs/permissions.md): Fortify session auth, Spatie roles, PermissionEnum, EffectivePermissionResolver, middleware, and frontend useCan.
- [Collections data model](https://docs.externa.qiick.io/docs/collections-data-model.md): EAV schema for collections, fields, items, and values — singleton mode, soft deletes, locales, and collection services.
- [Field types](https://docs.externa.qiick.io/docs/field-types.md): Every FieldTypeEnum value — storage shape, relation flags, and settings JSON options for collection fields.
- [Field conditions](https://docs.externa.qiick.io/docs/field-conditions.md): Operators, AND/OR logic, and examples for dynamic show / hide / readonly / required on collection item forms.
- [Schema changes](https://docs.externa.qiick.io/docs/schema-changes.md): Renaming fields and changing types with existing content — behaviour from externa-core 1.2.1, repair command, and type-change risks.
- [File tree model](https://docs.externa.qiick.io/docs/file-tree-model.md): File nodes, versions, chunked uploads, fileables, tags, favorites, assets disk, thumbnails, and async zip/duplicate thresholds.
- [AI assistant model](https://docs.externa.qiick.io/docs/ai-assistant.md): AppAssistant tools, conversations, attachments, daily limits, embeddings-backed SearchSimilar, and MCP flag in externa-core.

## Features

- [Dashboard](https://docs.externa.qiick.io/docs/dashboard.md): Dashboard Overview widgets and Health tab with native Pulse/Horizon metrics — no primary Open Pulse or Open Horizon CTAs.
- [Users & groups](https://docs.externa.qiick.io/docs/users-and-groups.md): Admin user CRUD with soft-delete lifecycle and bulk actions, plus groups that attach members and roles for permission inheritance.
- [Roles & permissions](https://docs.externa.qiick.io/docs/roles-and-permissions.md): Role and permission CRUD, bulk role delete, and syncing the Spatie permission table from PermissionEnum.
- [Collections](https://docs.externa.qiick.io/docs/collections.md): Collection CRUD with slug, singleton flag, sort order, soft-delete cascade to items, and the fields builder.
- [Collection items](https://docs.externa.qiick.io/docs/collection-items.md): Item CRUD, History revisions, advanced filters, singleton upsert, and relational/M2M editing.
- [Collection layouts](https://docs.externa.qiick.io/docs/collection-layouts.md): Optional kanban and calendar layouts for collection item lists — board columns, date fields, and how layouts map to item data.
- [Collaborative editing](https://docs.externa.qiick.io/docs/collaborative-editing.md): Item-level presence, soft edit lock, and stale-save warnings via Laravel Echo and Reverb.
- [Meilisearch sync](https://docs.externa.qiick.io/docs/meilisearch.md): Optional Meilisearch indexer for published collection items — Compose sidecar, env config, and headless starter query notes.
- [Git export sync](https://docs.externa.qiick.io/docs/git-export.md): Optional content-as-code export of published collection items to a git remote via deploy key.
- [Content versioning](https://docs.externa.qiick.io/docs/content-versioning.md): Lean draft/publish model with draft_data, promote, discard, and revision history — not a full multi-branch CMS versions engine.
- [Editorial approvals](https://docs.externa.qiick.io/docs/approvals.md): Optional submit → review → approve/reject → publish workflow for versioned collections.
- [Translation workspace](https://docs.externa.qiick.io/docs/translation-workspace.md): Locale switcher, copy helpers, completeness, and optional AI translate on the item form (externa-core 1.2.1).
- [Live Preview](https://docs.externa.qiick.io/docs/live-preview.md): Per-collection frontend preview URL templates with signed short-lived tokens — draft vs published bridge without embedding API keys.
- [File manager](https://docs.externa.qiick.io/docs/file-manager.md): Browse, upload, version, organize, zip, and duplicate files under /files with can.manage.files permission mapping.
- [AI chat](https://docs.externa.qiick.io/docs/ai-chat.md): AI page and FAB chat with streaming, pinned conversations, CSV/TXT/XLSX/PDF attachments, throttle, and action presets.
- [Chat (hub & items)](https://docs.externa.qiick.io/docs/chat.md): Unified team chat — collection item threads, direct messages, per-user archive, hub UI, attachments, realtime Echo, unread, mentions, and activity logging.
- [AI imports & sync](https://docs.externa.qiick.io/docs/ai-imports-and-sync.md): CSV and remote JSON import tools, dry_run and upsert_key, jobs, webhook, scheduled AiSyncSource sync, export, PDF extract, and rollback.
- [CMS import connectors](https://docs.externa.qiick.io/docs/cms-import.md): Migrate from Directus or WordPress into Externa collections via ImportRemoteJson profiles, dry-run, upsert, and host allowlist.
- [Activity & notifications](https://docs.externa.qiick.io/docs/activity-and-notifications.md): Spatie activitylog, auth events, Activity Log UI, QueryActivityLogs, file/chat notifications, and the bell mark-read / mark-unread API.
- [Account settings](https://docs.externa.qiick.io/docs/account-settings.md): Profile, password, Fortify two-factor authentication and passkeys, UI locale, and personal theme preference.
- [Passkeys](https://docs.externa.qiick.io/docs/passkeys.md): Passwordless WebAuthn passkeys in Externa — register, sign in, two-factor, APP_URL / RP config, Herd TLS, and security notes.
- [SSO / OIDC](https://docs.externa.qiick.io/docs/sso-oidc.md): Optional OpenID Connect login — issuer discovery, encrypted client secret, link-by-email, JIT provisioning, redirect URI, and security notes.
- [Accessibility](https://docs.externa.qiick.io/docs/accessibility.md): User accessibility preferences, OS media queries, skip link, and WCAG AA targets on P0 admin flows.
- [Project settings](https://docs.externa.qiick.io/docs/project-settings.md): Project settings — locales, modules, password policy, registration, API origins, file transforms, webhooks, notifiers, SSO, and branding.

## Configuration

- [Application config](https://docs.externa.qiick.io/docs/configuration.md): App identity, locales, Fortify features, session/cache/queue defaults, super-admin seeding, and permission/collections config overview.
- [Files & storage](https://docs.externa.qiick.io/docs/files-configuration.md): File manager thresholds, local/public/assets disks, FILE_PUBLIC_URL_BASE, optional S3, cleanup commands, and storage:link.
- [AI configuration](https://docs.externa.qiick.io/docs/ai-configuration.md): Default local AI provider, LOCAL_AI_* keys, cloud providers, remote import hosts, webhook token, limits, embeddings, MCP, and conversation tables.

## HTTP reference

- [Routing overview](https://docs.externa.qiick.io/docs/routing.md): How web.php composes domain routes, middleware layers, session-cookie Inertia/JSON APIs, and shared Inertia props.
- [Admin & files API](https://docs.externa.qiick.io/docs/admin-api.md): Admin HTTP routes for users, groups, roles, permissions, activity logs, and the full files JSON/Inertia surface with permission notes.
- [Collections API](https://docs.externa.qiick.io/docs/collections-api.md): Session HTTP routes for collections, fields, and items — Spatie permission gates, bulk actions, export, revisions, and packs.
- [Public CMS API](https://docs.externa.qiick.io/docs/public-cms-api.md): How Externa’s headless /api/v1 collections API works — public role, collection access matrix, API keys, auth resolution, setup, and endpoint reference.
- [Public CMS API types](https://docs.externa.qiick.io/docs/public-cms-api-types.md): Copyable TypeScript interfaces, OpenAPI 3, and JSON Schema for Externa Public CMS API (/api/v1) create/update payloads and main responses.
- [GraphQL](https://docs.externa.qiick.io/docs/graphql.md): Public CMS GraphQL API at /api/graphql — same auth and collection guards as REST, with collections/items queries and mutations.
- [API 1.x compatibility](https://docs.externa.qiick.io/docs/api-compatibility.md): What Externa guarantees for /api/v1 and GraphQL during 1.x — additive changes, deprecations, and breaking major rules.
- [AI API & webhooks](https://docs.externa.qiick.io/docs/ai-api.md): Collection-import webhook and authenticated /ai/* routes for status, conversations, attachments, chat, import jobs, and deep links.
- [Outbound webhooks](https://docs.externa.qiick.io/docs/webhooks.md): Configure a project webhook URL to receive HMAC-signed domain events for items, files, and collections.
- [Slack & Telegram notifiers](https://docs.externa.qiick.io/docs/integrations.md): Optional Slack incoming webhook and Telegram bot notifications for Externa domain events.
- [Webhook rebuild & CDN purge](https://docs.externa.qiick.io/docs/webhook-rebuild-purge.md): Copy-paste recipes — Externa outbound webhooks to Vercel/Netlify deploy hooks and Cloudflare cache purge.

## Operations

- [Queues & scheduler](https://docs.externa.qiick.io/docs/operations.md): Queue workers, scheduled cleanup and sync commands, permissions:sync, health checks, and observability with Pail and activity logs.
- [Automation without Flows](https://docs.externa.qiick.io/docs/automation-without-flows.md): Code-first automation with Laravel listeners, jobs, scheduler, and outbound webhooks — Externa does not ship a Directus Flows clone.
- [Mail providers](https://docs.externa.qiick.io/docs/mail-providers.md): Production .env examples for SMTP, Amazon SES, Postmark, and Mailgun with Externa Core.
- [Redis prerequisite](https://docs.externa.qiick.io/docs/redis-prerequisite.md): Why Externa needs Redis for Horizon, app cache, Reverb scaling/presence, and Pulse ingest, and how to enable it with Laravel Herd.
- [Horizon](https://docs.externa.qiick.io/docs/horizon.md): Laravel Horizon for Redis queues — Health-tab native metrics, gates, Supervisor, and local commands. No primary Open Horizon CTA.
- [Reverb & Echo](https://docs.externa.qiick.io/docs/reverb-and-echo.md): Laravel Reverb WebSockets, Echo client, private notification channels, avatar connection indicator, and presence online users.
- [Pulse & Health tab](https://docs.externa.qiick.io/docs/pulse-and-health.md): Laravel Pulse with redis ingest, short trim, essential recorders, and native dashboard Health metrics without Open Pulse CTAs.
- [Performance tuning](https://docs.externa.qiick.io/docs/performance-tuning.md): Public API response cache, include costs, queues/Horizon, and how to read Pulse for CMS hotspots.
- [Minimal vs full stack](https://docs.externa.qiick.io/docs/minimal-vs-full-stack.md): Run Externa without Redis (database queue + log broadcast) or with Horizon, Herd Reverb, and Pulse.
- [Deployment](https://docs.externa.qiick.io/docs/deployment.md): Production deploy checklist — secrets, migrate, seed/sync permissions, storage link, queue, scheduler, AI gateway, APP_URL, and leaving SQLite.
- [Deploy with Docker](https://docs.externa.qiick.io/docs/deploy-with-docker.md): One-command self-hosted Externa — pull GHCR multi-arch image, minimal .env, Compose up, gated first-boot, healthchecks.
- [Reverse proxy cookbook](https://docs.externa.qiick.io/docs/reverse-proxy.md): Put Externa behind Caddy, Traefik, or nginx — TLS, TRUSTED_PROXIES, APP_URL, and Reverb WebSockets.
- [Upgrade](https://docs.externa.qiick.io/docs/upgrade.md): Stay current after install — git tags, externa:upgrade --sync-upstream, or Docker image bump; then migrate, permissions, and cache.
- [Backup & restore](https://docs.externa.qiick.io/docs/backup-restore.md): Backup and restore a self-hosted Externa — database, storage, .env, Docker volumes, and S3 caveats.
- [Production without Redis](https://docs.externa.qiick.io/docs/production-without-redis.md): Run Externa in production with database queues and log broadcast when Redis is unavailable — capability matrix and supervisor examples.
- [Releasing & versions](https://docs.externa.qiick.io/docs/releasing.md): How to cut an Externa Core release — semver, CHANGELOG, version bump checklist, and GitHub Releases.
- [Changelog](https://docs.externa.qiick.io/docs/changelog.md): Per-version history of Externa Core releases — what shipped in each beta, with links to GitHub Releases and issues.
- [Threat model & hosting](https://docs.externa.qiick.io/docs/threat-model.md): What Externa protects by default, what operators must provide (TLS, disk encryption, backups), and how activity log / chat data are stored.
- [AuthZ map](https://docs.externa.qiick.io/docs/authz-map.md): Surface → gate → Pest map for Spatie permissions, collection ACL, file read_private, GraphQL, AI tools, and webhooks.
- [Security checklist](https://docs.externa.qiick.io/docs/security-checklist.md): Must-pass security gates before shipping Externa v1 (collections Gate, field rules, GraphQL).

## Contributing

- [How to contribute](https://docs.externa.qiick.io/docs/contributing.md): Pint, ESLint/Prettier, Wayfinder, Pest, coding conventions for Actions/Services and enums, and keeping the graphify knowledge graph updated.
- [Extending Externa](https://docs.externa.qiick.io/docs/extending.md): How to add permissions, collection field types, and AI tools end-to-end with enums, sync, middleware, useCan, and tests.
- [Testing](https://docs.externa.qiick.io/docs/testing.md): Pest 4 layout for Admin, Ai, Collections, Auth and more, browser plugin notes, how to run tests, and coverage expectations for new features.