# Knowledge Base — Improvement & Growth Plan > Package: capell-app/knowledge-base · Kind: package · Tier: premium · Product group: Capell Content · Bundle: content-product · Status: Complete ## 1. Snapshot Knowledge Base owns five tables (`knowledge_base_collections`, `knowledge_base_articles`, `knowledge_base_article_versions`, `knowledge_base_article_feedback`, `knowledge_base_related_articles`) and two Filament resources (Collections, Articles), plus four public routes under `/docs` (index, article, feedback POST, and `llms.txt` AI output). Domain logic lives in Actions; the public-facing ones (`BuildPublicKnowledgeBaseNavigationAction`, `BuildPublicKnowledgeBaseArticleDataAction`, `BuildAiReadableKnowledgeBaseOutputAction`) feed hydrated Data objects into thin public controllers and Blade views that hold no DB queries, and the public-output safety story is well-tested. Deps are lean: `capell-app/core`, `capell-app/admin`, `capell-app/frontend`, `lorisleiva/laravel-actions`, `spatie/laravel-data` (no Scout, no medialibrary, no translatable). Current marketplace `summary` (verbatim): _"Versioned docs content, public knowledge navigation, feedback capture, related articles, and AI-readable documentation output."_ — marketplace screenshot count: **2** promoted Capell admin PNGs, plus two public route evidence PNGs documented in `docs/screenshots.json`. The headline gap has narrowed: article and collection Edit pages now exist, article updates create/publish versions, related article type/order editing is exposed, feedback aggregate signals are visible to authors/readers, public routes participate in Capell Frontend middleware/cache where available, `/docs/llms.txt` exposes AI-readable output, Capell Search can index Knowledge Base articles through a registered `knowledge-base` source, and `capell:knowledge-base-demo` seeds screenshot-ready demo content. ## 2. Improvements (existing functionality) Prioritized: 1. **Done/Shipped: Add Edit pages to both Filament resources.** Article and Collection resources now register `edit` pages. Collection edits delegate to `UpdateKnowledgeBaseCollectionAction`; article edits delegate to `UpdateKnowledgeBaseArticleAction`, so resource pages expose a real revision surface instead of create-only authoring. Evidence: `KnowledgeBaseAdminSurfaceTest` covers edit page registration. — `src/Filament/Resources/Articles/KnowledgeBaseArticleResource.php`, `src/Filament/Resources/Collections/KnowledgeBaseCollectionResource.php` 2. **Done/Shipped: Wire the Edit page to `CreateKnowledgeBaseArticleVersionAction` + `PublishKnowledgeBaseArticleVersionAction`.** `EditKnowledgeBaseArticle` now saves through `UpdateKnowledgeBaseArticleAction`, which creates a new article version and publishes it through the existing publish Action when the submitted status is Published. The article resource exposes a read-only Version history relation manager with version, title, current-version, published, and created columns. Evidence: `KnowledgeBaseAdminSurfaceTest` covers the edit-page adapter and version history table; `KnowledgeBaseFoundationActionsTest` covers direct publish-on-update Action behavior. — `src/Actions/UpdateKnowledgeBaseArticleAction.php`, `src/Filament/Resources/Articles/Pages/EditKnowledgeBaseArticle.php`, `src/Filament/Resources/Articles/RelationManagers/ArticleVersionsRelationManager.php` 3. **Done/Shipped: Throttle and dedupe the public feedback endpoint.** The anonymous feedback route uses configurable `throttle` middleware (`capell-knowledge-base.feedback.throttle`, default `30,1`), and repeat feedback from the same visitor for the same article version updates the existing `visitor_hash` row instead of creating duplicate votes. Evidence: README/CHANGELOG document the shipped behavior, and focused route/action coverage exists. — `routes/web.php`, `src/Actions/RecordKnowledgeBaseArticleFeedbackAction.php`, `tests/Feature/Frontend/KnowledgeBasePublicRoutesTest.php`, `tests/Feature/Actions/KnowledgeBaseFoundationActionsTest.php` — **S** 4. **Done/Shipped: Route public requests through Capell frontend middleware.** `routes/web.php` now uses `FrontendRouteMiddlewareRegistry` when the Frontend package is available, and the package declares `capell-app/frontend` as a direct dependency. The provider also registers Knowledge Base article, version, and collection model dependencies with `CacheInvalidationRegistry` when the Frontend cache registry is bound, so compatible HTML cache/model-event middleware can participate in `/docs` delivery. — `routes/web.php`, `src/Providers/KnowledgeBaseServiceProvider.php`, `composer.json`, `capell.json` — **M** 5. **Done/Shipped: expose AI-readable public output.** `/docs/llms.txt` now consumes `BuildAiReadableKnowledgeBaseOutputAction` and emits a cacheable `text/plain` Markdown-style listing of published, public, AI-readable articles without authoring metadata. Evidence: route coverage asserts the endpoint includes the published article and excludes drafts/admin internals. — `routes/web.php`, `src/Http/Controllers/ShowKnowledgeBaseAiOutputController.php`, `tests/Feature/Frontend/KnowledgeBasePublicRoutesTest.php` — **M** 6. **Done/Shipped: guard article slug collisions** — `CreateKnowledgeBaseArticleAction` now checks for an existing slug in the target collection and returns a translated `ValidationException` instead of letting the database unique key surface a raw `QueryException`. Evidence: `KnowledgeBaseFoundationActionsTest` covers same-collection duplicate rejection while allowing the same slug in a different collection. — `src/Actions/CreateKnowledgeBaseArticleAction.php`, `tests/Feature/Actions/KnowledgeBaseFoundationActionsTest.php` 7. **Done/Shipped: expose feedback signal in the admin table and public page.** The Article table now preloads feedback counts and helpful counts, then shows vote count and helpful-rate columns. Public article DTOs carry feedback totals/percentage and the Blade view displays a translated helpfulness summary only when votes exist, keeping aggregate queries out of public Blade. — `src/Filament/Resources/Articles/KnowledgeBaseArticleResource.php`, `src/Actions/BuildPublicKnowledgeBaseArticleDataAction.php`, `src/Data/PublicKnowledgeBaseArticleData.php`, `resources/views/article.blade.php` — **S** 8. **Done/Shipped: make `relation_type` / `sort_order` editable for related articles.** The Article edit surface now includes a Related Articles relation manager. Authors can relate an article, choose `Prerequisite` / `NextStep` / `Related`, set display order, and update existing relations through `RelateKnowledgeBaseArticlesAction`. Evidence: admin surface coverage asserts the relation manager registration, columns, and relate/update actions. — `src/Filament/Resources/Articles/RelationManagers/RelatedArticlesRelationManager.php`, `src/Filament/Resources/Articles/KnowledgeBaseArticleResource.php`, `tests/Feature/Filament/KnowledgeBaseAdminSurfaceTest.php` — **M** ## 3. Missing Features (gaps) Mapped to `capabilities[]` and KB-category norms. **Table-stakes** = expected of any KB product; **Differentiator** = sets it apart. - **Done/Shipped: full-text search integration.** Knowledge Base now registers a `knowledge-base` source with Capell Search when the Search registry is available, and `KnowledgeBaseArticle::toSearchableArray()` exposes public-safe title, URL, excerpt, body, type, status, timestamp, collection, version, and weight metadata for the Scout-backed source path. The legacy `BuildKnowledgeBaseSearchDocumentsAction` remains useful as a typed export/building-block API. — `src/Providers/KnowledgeBaseServiceProvider.php`, `src/Models/KnowledgeBaseArticle.php`, `src/Actions/BuildKnowledgeBaseSearchDocumentsAction.php` - **Done/Shipped: AI-assisted / AI-readable output route (differentiator).** `BuildAiReadableKnowledgeBaseOutputAction` is now exposed through `/docs/llms.txt`, delivering the advertised `knowledge-base-ai-output` capability as a cacheable plain-text endpoint for published, public, AI-readable articles. — `src/Actions/BuildAiReadableKnowledgeBaseOutputAction.php`, `src/Http/Controllers/ShowKnowledgeBaseAiOutputController.php` - **Done/Shipped: article feedback aggregation & ratings surface.** Raw votes are stored, the admin Article table shows vote counts and helpful rate, and public articles display a helpfulness summary once feedback exists. A broader admin report can remain future reporting depth. - **Done/Shipped: cache `variesBy` now matches product scope.** The manifest no longer claims site/locale-specific cache variants because Knowledge Base article content is currently global and single-locale. Collection invalidation is also declared alongside article and version invalidation so manifest metadata matches provider registration. Full persisted `site_id` and translatable article bodies remain future product depth rather than shipped cache-safety claims. — `capell.json`, `src/Providers/KnowledgeBaseServiceProvider.php` - **Done/Shipped: categories/collections nesting in public output.** `BuildPublicKnowledgeBaseNavigationAction` now builds a recursive public collection tree, preserving parent collections that have child article groups even when the parent has no direct articles. The public index renders nested collections through a recursive partial without running queries in Blade. — `src/Actions/BuildPublicKnowledgeBaseNavigationAction.php`, `resources/views/partials/collection-navigation.blade.php` - **Done/Shipped: admin policies are no longer wide-open.** Knowledge Base article and collection policies now require Shield permissions, allow global admins, and enforce record `site_id` membership when a record exposes a site id. The package still needs real persisted `site_id` scoping before it can be multi-site complete. Evidence: `KnowledgeBasePolicyTest` covers unauthorized denial, Shield-authorized access, global admin access, and site-id mismatch denial. - **Search-within-article / table of contents, article tags, view counts, "last updated" display (table-stakes polish).** None present; the public article view shows title/summary/body/related only. - **Done/Shipped: demo command.** `capell:knowledge-base-demo` seeds public collections, published articles, a next-step related link, and sample positive/negative feedback using portable semantic article HTML. The command is registered in `capell.json` as the package demo command. — `src/Console/Commands/DemoCommand.php`, `capell.json` ## 4. Issues / Risks - **Done/Shipped: real health check.** `KnowledgeBaseHealthCheck` now reports Diagnostics checks for required storage tables, Knowledge Base models, domain Actions, admin resources, and runtime/admin providers. Evidence: `tests/Feature/Health/KnowledgeBaseHealthCheckTest.php` covers the passing diagnostic set and missing-table failure mode. — `src/Health/KnowledgeBaseHealthCheck.php` - **Done/Shipped: Manifest cache/invalidation is wired to Frontend where available.** `performance.cacheTags: ["knowledge-base"]`, `queueInvalidation: true`, `variesBy: []`, and the collection/article/version invalidation list now have a matching bootstrap hook: Knowledge Base registers article, version, and collection model dependencies with `CacheInvalidationRegistry` when Frontend is installed. Public responses still keep the short `Cache-Control: max-age=300` header for HTTP clients. — `capell.json`, `routes/web.php`, `src/Providers/KnowledgeBaseServiceProvider.php` - **Done/Shipped: dead capability surfaces have been reduced.** Version Actions are reachable through the Article Edit flow, related-article editing is reachable through the Article relation manager, AI output is reachable through `/docs/llms.txt`, Search can discover a `knowledge-base` source when installed, Site Discovery can discover `/docs/*` public URLs, and Theme Knowledge ships KB payload templates. - **Done/Shipped: policies use Shield permissions and opportunistic site checks.** `KnowledgeBaseArticlePolicy` and `KnowledgeBaseCollectionPolicy` now delegate to a shared base policy that uses `ResolvesShieldPermission`, denies ordinary users, allows global admins, and blocks record access when a `site_id` is present but outside the actor's assigned sites. Full persisted KB site scoping remains a schema/product gap because article and collection tables do not yet carry a site ownership field. — `src/Policies/AbstractKnowledgeBaseResourcePolicy.php`, `tests/Unit/Policies/KnowledgeBasePolicyTest.php` - **Done/Shipped: anonymous feedback endpoint is throttled, deduped, and surfaced.** The previous abuse/ballot-stuffing risk is mitigated through route throttle middleware plus visitor/article-version row updates. Feedback aggregates now appear in both the public article DTO/view and the admin Article table. — `routes/web.php`, `src/Actions/RecordKnowledgeBaseArticleFeedbackAction.php`, `src/Actions/BuildPublicKnowledgeBaseArticleDataAction.php`, `src/Filament/Resources/Articles/KnowledgeBaseArticleResource.php` - **Test gaps.** Feature coverage includes public rendering safety (strong), AI-output route safety, public-safe search payloads, feedback redaction, feedback throttle/dedupe and aggregate DTO values, manifest shape, admin-resource registration, real health diagnostics, article slug-collision validation, and the Article Edit/version/related-article surfaces. **Not covered:** public related-article ordering edge cases and deeper AI-output Action filtering edge cases beyond the current public-route draft/private exclusion checks. No Unit suite. — `tests/Feature/` - **Performance budget unverifiable.** `frontendRenderBudgetMs: 20` / `adminQueryBudget: 40` are declared but no test or benchmark enforces them. `BuildPublicKnowledgeBaseNavigationAction` eager-loads `articles.currentVersion` (good), but the article controller eager-loads `relatedArticleLinks.relatedArticle.collection` + `.currentVersion` two levels deep on every hit with no cap on related count. - **i18n is partial by product scope.** All admin/frontend strings are translated (`resources/lang/en/generic.php`), but the content is single-locale (no translatable article bodies). The manifest now reflects this by not claiming a locale cache variant. - **Done/Shipped: docs/README/CHANGELOG are no longer empty.** README, docs README, and CHANGELOG now describe shipped routes, feedback safety, Search integration, demo content, and screenshot evidence. Deeper private docs can still expand host-app installation and cross-package recipes. ## 5. Marketplace & Selling **Critique.** The composer `description` ("Knowledge base collections, versioned articles, feedback, and public docs discovery for Capell") and the marketplace `summary` now broadly match shipped capability depth. Versioned article editing, related-article management, feedback aggregates, AI-readable output, Search source registration, Site Discovery metadata, Theme Knowledge reference templates, demo content, and runner-backed screenshots are reconciled. Remaining commercial polish is accepted future product depth rather than an open roadmap row. **Improved 1-sentence summary:** > A self-hosted help centre for Capell: organise docs into collections, publish versioned articles, capture reader feedback, and expose a clean public docs site plus AI-readable output — no theme lock-in. **Improved 3–4 sentence description:** > Knowledge Base turns your Capell install into a structured help centre. Authors group articles into nestable collections and publish them with full version history, while readers browse a fast, cacheable `/docs` site and tell you whether each article helped. Public navigation, article, and AI-readable payloads are emitted as typed data objects, so any theme can render them and assistants can consume them without leaking authoring internals. Pairs with the Search and SEO Suite extensions to make every article findable by humans and machines. (This copy now matches the shipped version, feedback, Search, Site Discovery, Theme Knowledge, and AI-output surfaces.) **Screenshot/media status:** `docs/screenshots.json` documents four runner-backed captures: Articles index, article edit/version history, public `/docs`, and public article. `capell.json` promotes the two Capell admin PNGs into marketplace media and keeps public route captures as supporting evidence. **Pricing / tier / bundle.** `premium` tier in the `content-product` bundle is now defensible for the shipped versioning, feedback, Search, Site Discovery, AI-output, admin authoring surfaces, and Theme Knowledge reference templates. **Differentiators / value props:** (1) first-class **version history** with publish workflow, (2) **AI-readable output** for LLM ingestion (rare in CMS KB add-ons), (3) **privacy-preserving feedback** (visitor/IP hashed with app-key salt — already implemented and tested), (4) **theme-agnostic typed payloads** that never leak admin internals. **Target buyer:** SaaS/product teams and agencies running Capell who need a docs/help centre without standing up a separate tool (Helpscout, Zendesk Guide, GitBook). **8–12 keywords/tags:** `knowledge-base`, `help-centre`, `documentation`, `docs-site`, `versioned-articles`, `article-feedback`, `related-articles`, `full-text-search`, `ai-readable`, `llms-txt`, `self-hosted`, `filament-cms`. ## 6. Prioritized Roadmap | Item | Bucket | Effort | Impact | Section ref | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | --------------------- | ----------- | | Done/Shipped: Add Edit pages to Article + Collection resources | Done | L | Critical | §2.1 | | Done/Shipped: Wire version-create + publish into the Edit flow (history relation manager) | Done | M | Critical | §2.2, §3 | | Done/Shipped: Throttle + dedupe the anonymous feedback endpoint. Evidence: route middleware is configurable, repeat visitor/article-version feedback updates the existing row, and focused route/action coverage exists. | Done | S | High (abuse) | §2.3, §4 | | Done/Shipped: implement a real `KnowledgeBaseHealthCheck` (models/tables/Actions/resources/providers discoverable) | Done | S | High (trust) | §4 | | Done/Shipped: Lock policies to Shield permissions + site access where records expose `site_id`. Evidence: policy tests cover denied ordinary users, Shield permissions, global admins, and site-id mismatch denial. | Done | M | High (security) | §4 | | Done/Shipped: slug-collision guard in `CreateKnowledgeBaseArticleAction` | Done | S | Medium | §2.5 | | Done/Shipped: Route `/docs` through Capell Frontend middleware registry + register cache dependencies. Evidence: Knowledge Base now requires Frontend, public routes consume `FrontendRouteMiddlewareRegistry` when bound, and article/version/collection models register `knowledge-base-*` cache dependencies. | Done | M | High | §2.4, §4 | | Done/Shipped: Search integration: register with `capell-app/search` and expose public-safe article search payloads | Done | L | Critical (category) | §3 | | Done/Shipped: Add `llms.txt`/AI-output route consuming `BuildAiReadableKnowledgeBaseOutputAction` | Done | M | High (differentiator) | §2.5, §3 | | Done/Shipped: Related-articles relation manager (type + order editable) | Done | M | Medium | §2.8, §3 | | Done/Shipped: Feedback aggregate column in admin + "was this helpful" stats on public page | Done | S | Medium | §2.7, §3 | | Done/Shipped: Resolve `variesBy` mismatch by correcting manifest cache-safety metadata to current global/single-locale scope | Done | M | Medium (correctness) | §4 | | Done/Shipped: Write README/docs/CHANGELOG + `demo` seeder command; reconcile runner-backed screenshots | Done | M | High (sales) | §4, §5 | | Done/Shipped: Nest child collections in public navigation output | Done | S | Low | §3 | | Done/Shipped: SEO/Site Discovery integration (Article schema data + `/docs/*` public URL/sitemap discovery) | Done | M | Medium (cross-sell) | §5 | | Done/Shipped: `theme-knowledge` reference templates for KB payloads | Done | M | Medium (bundle) | §5 |