Knowledge lifecycle
Manual home · Role guides · Coverage · Gaps
Manual conventions and recovery apply to every workflow. Evidence level: code inspected; related tests were inspected, not executed.
flowchart TD
A[Create or edit draft] --> B[Save expected revision]
B --> C[Preview and review]
C --> D[Explicit publish]
D --> E[Reader visible revision]
E --> F[Announce to eligible agents]
E --> G[New draft or restored historical snapshot]
G --> B
E --> H[Archive or move to draft]
H --> I{Deletion references clear?}
I -->|Yes| J[Permanent delete]
I -->|No| K[Retain and review dependencies]
KNO-01 — Find published knowledge and inspect pinned sections
Status: Implemented. Verification: code inspected; no runtime completion claim.
Purpose: find published knowledge and inspect pinned sections.
Actors and access: qms:read for published reader/search/retrieval operations.
Prerequisites: Published tenant knowledge or a valid historical pinned citation.
Entry point: Knowledge browse/article; cited knowledge links.
- Search by text/category/tags and open a published article.
- Follow section citations and revision context when reviewing scoring evidence; use related articles for supporting context.
- Inspect attachments through the article's permitted reader view.
Result: Readers retrieve accessible knowledge; scoring citations retain their pinned revision.
Exceptions and recovery: Draft/archived or unavailable content is not generally reader-visible. A newer article does not rewrite Atom citations. Use KNO-03 and deliberate definition revision to refresh scoring sources.
Source evidence: services/api/src/knowledge/routes.ts; services/api/src/knowledge/article-sections.ts; apps/web/src/features/knowledge/knowledge.tsx.
KNO-02 — Create, edit and preview a knowledge draft
Status: Implemented. Verification: code inspected; no runtime completion claim.
Purpose: create, edit and preview a knowledge draft.
Actors and access: knowledge:write.
Prerequisites: A unique article code and valid tenant metadata/related references.
Entry point: Knowledge → New / Drafts / editor.
- Create the article with code, title, body and supported metadata.
- Edit structure and content, use preview, and explicitly save the draft.
- Review the current draft revision and any linked scoring usage before publishing.
Result: Saved draft changes remain separate from reader-visible publication.
Exceptions and recovery: The article code is immutable after creation. Stale revisions require reload/reconciliation; unavailable inline images and invalid related-article links must be fixed before saving/publishing.
Source evidence: services/api/src/knowledge/routes.ts; apps/web/src/features/knowledge/knowledge.tsx.
KNO-03 — Publish, restore, archive or delete knowledge
Status: Implemented. Verification: code inspected; no runtime completion claim.
Purpose: publish, restore, archive or delete knowledge.
Actors and access: knowledge:publish to publish; knowledge:write for draft/archive/history/restore/delete.
Prerequisites: An existing article and valid draft revision.
Entry point: Knowledge article/editor → lifecycle actions.
- Publish explicitly to make reviewed content available to readers.
- For revisions, edit/save a draft; inspect history and restore a historical snapshot into a draft, then save/publish deliberately.
- Move to draft/archive when withdrawing content. Inspect usage before permanent deletion.
Result: Readers see published revisions; historical scoring definitions keep their original pinned revisions.
Exceptions and recovery: Deletion requires an unpublished/archived article with no blocking related-article or Atom-version references. Restoring history does not itself publish it. Source deletion may make prior citations unavailable; review dependencies first.
Source evidence: services/api/src/knowledge/routes.ts; apps/web/src/features/knowledge/knowledge.tsx.
KNO-04 — Upload, use and remove knowledge assets
Status: Implemented. Verification: code inspected; no runtime completion claim.
Purpose: upload, use and remove knowledge assets.
Actors and access: knowledge:write to mutate; asset read access follows article visibility.
Prerequisites: Supported file type/size and configured storage.
Entry point: Knowledge editor → Attachments; content library.
- Request upload authorisation, upload the bytes and complete server verification.
- Insert available images inline or keep files as downloadable attachments; inspect the content library for usage/status.
- Remove live references before deleting an eligible attachment.
Result: Verified assets are attached to the article and exposed through permitted reader paths.
Exceptions and recovery: Integrity mismatches quarantine uploads. In-use assets cannot be deleted. Missing storage/content-reader configuration prevents playback/download; do not attach an unverified upload as if it were available.
Source evidence: services/api/src/knowledge/routes.ts; services/api/src/knowledge/attachment-usage.ts; apps/web/src/features/knowledge/knowledge-rich-content.tsx.
KNO-05 — Maintain categories, tags and article owners
Status: Implemented. Verification: code inspected; no runtime completion claim.
Purpose: maintain categories, tags and article owners.
Actors and access: knowledge:write; owner assignment validates active tenant members.
Prerequisites: Existing article/taxonomy where editing; valid member directory.
Entry point: Knowledge → Categories/Tags; article ownership controls.
- Create or rename supported categories/tags and apply them to drafts.
- Assign or clear the article's responsible owner.
- Delete unused taxonomy entries only after removing article references.
Result: Knowledge metadata and ownership are maintained within the tenant.
Exceptions and recovery: Duplicate names and in-use taxonomy deletion are rejected. Owner selection must resolve to an active tenant member. Ownership does not itself grant publication permission.
Source evidence: services/api/src/knowledge/routes.ts; apps/web/src/features/knowledge/knowledge.tsx.
KNO-06 — Enrich a knowledge draft with reviewed AI changes
Status: Implemented. Verification: code inspected; no runtime completion claim.
Purpose: enrich a knowledge draft with reviewed AI changes.
Actors and access: knowledge:write; configured enrichment dependencies.
Prerequisites: An article revision, jobs/taxonomy services and configured LLM processing.
Entry point: Knowledge editor → Enrichment review.
- Request editorial or structure/metadata enrichment and monitor its job.
- Compare current/proposed content and suggested category/tag additions.
- Apply selected changes explicitly or discard them; save/publish through the normal article lifecycle.
Result: Accepted changes update the expected draft revision.
Exceptions and recovery: A changed source revision causes a conflict instead of overwriting newer content. Invalid inline assets block application. A generated taxonomy suggestion is not silently accepted merely by displaying it.
Source evidence: services/api/src/knowledge/routes.ts; services/api/src/knowledge/enrichment.ts; apps/web/src/features/knowledge/knowledge.tsx.
KNO-07 — Announce published knowledge and remind managers
Status: Implemented. Verification: code inspected; no runtime completion claim.
Purpose: announce published knowledge and remind managers.
Actors and access: knowledge:publish; active tenant agents are recipients.
Prerequisites: Published article, configured mailer/public app URL, and a non-empty supported audience.
Entry point: Knowledge article → Announcements.
- Choose all active agents, one active team or selected agents; explicitly send the announcement.
- Inspect delivery and read status for the campaign.
- Use the reminder action for managers with unread assigned agents and inspect delivery outcomes.
Result: A campaign tracks delivery and recipient article opens; reminders are deliberate sends.
Exceptions and recovery: Missing delivery configuration prevents sending. An article open/read signal is not proof of mastery or quiz completion. No eligible unread-manager reminders is a handled condition, not a reason to send to unrelated users.
Source evidence: services/api/src/knowledge/routes.ts; services/api/src/knowledge/announcement-repository.ts; apps/web/src/features/knowledge/knowledge-announcements.tsx.