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