Initial curated itworx-knowledge-hub source from 3b1751d0d9dee551aa6994eee0093704dc334817

docs/15-project-hub.md

@@ -0,0 +1,170 @@
+# Project hub
+
+## Purpose
+
+Project dossiers turn scattered project notes into a reliable current-state and history
+view while keeping long-form documents as normal wiki pages.
+
+A project is not a duplicate folder. It is a structured aggregate linked to pages,
+decisions, runbooks, updates and milestones.
+
+## Project fields
+
+Required:
+
+- name;
+- slug;
+- concise summary;
+- lifecycle status;
+- priority;
+- current-state Markdown;
+- owner;
+- created/updated timestamps.
+
+Optional:
+
+- start/target/completion dates;
+- repository URL;
+- live URL;
+- documentation URL;
+- issue tracker URL;
+- technologies;
+- icon/image;
+- visibility classification;
+- external identifiers.
+
+URLs are validated and never used for server-side fetches in v1.
+
+## Lifecycle
+
+```text
+Concept → Planned → Active ↔ Blocked
+                         ↘ Maintenance
+Any non-archived state → Paused
+Active/Maintenance → Completed
+Any state → Archived
+```
+
+Transitions are flexible enough for personal projects but recorded in project history.
+Archived projects remain searchable by explicit filter and API permission.
+
+## Project overview
+
+The page contains:
+
+1. status and summary;
+2. current verified state;
+3. primary links and technologies;
+4. active milestones;
+5. recent project updates;
+6. accepted/current decisions;
+7. important runbooks;
+8. linked architecture/deployment/testing/troubleshooting pages;
+9. known issues/documentation warnings;
+10. revision/history access.
+
+The default view is concise. It does not render every full linked document.
+
+## Project documents
+
+A page can be linked with a role:
+
+- Overview
+- Current state
+- Architecture
+- Deployment
+- Infrastructure
+- Security
+- Testing
+- Troubleshooting
+- Release
+- User documentation
+- Other
+
+One page may be linked to multiple projects where meaningful. The page remains canonical;
+the project stores the relationship, not a copy.
+
+## Project updates
+
+Categories:
+
+- Progress
+- Feature
+- Fix
+- Deployment
+- Validation
+- Release
+- Decision
+- Risk
+- Blocker
+- Documentation
+- Maintenance
+
+An update includes title, bounded summary Markdown, occurred time, actor/source,
+verification status and optional references:
+
+- commit SHA;
+- release/tag;
+- issue identifier;
+- URL;
+- page;
+- decision;
+- milestone;
+- attachment.
+
+Verification status:
+
+- Reported
+- Verified
+- Superseded
+
+The UI must distinguish reported agent/user claims from validated evidence.
+
+## Project milestones
+
+Project-specific milestones have:
+
+- name;
+- order;
+- state;
+- target date;
+- completion date;
+- summary;
+- success criteria;
+- linked updates/documents.
+
+They do not reuse repository build milestone IDs.
+
+## Project context bundle
+
+The bounded context API is designed for external retrieval:
+
+- project identity/status/summary/current state;
+- configurable number of recent verified updates;
+- active milestones;
+- accepted decisions;
+- validated runbooks;
+- selected document summaries and citations;
+- known blockers;
+- explicit truncation information.
+
+It must not synthesize facts that are not stored. Summaries are stored/maintained fields,
+not automatic LLM output in v1.
+
+## Dashboard behavior
+
+Active projects show:
+
+- name/status;
+- one-line current state;
+- last verified update;
+- stale/documentation warning;
+- direct open action.
+
+Cards use consistent heights and alignment without hiding essential content.
+
+## Deletion/archive
+
+Projects archive by default. Deletion cannot delete linked pages. Timeline, decision and
+audit history remains recoverable. A privileged purge path requires explicit dependency
+review.