How to use Knowledge OS
Context
Knowledge OS (KO) is Aspire's shared knowledge base: one git-backed markdown vault that is read by humans as this website and read by AI agents as structured data. If you need to know "how does X work at Aspire", "who decided Y", or "what's the state of project Z" — it should be answered here, with sources.
Detail
Reading (everyone)
- Browse this site: https://ko-docs.aspiredigital.group — grouped by business domain
(shared / adg / alby / goldroom / chanya / venice / six-degrees) then by page type.
- Every project page has an Architecture diagram; every page ends with Provenance
(where the facts came from) and Related links.
- Worked example of KO in action: labour-vs-sales — raw Tanda +
POS data turned into a rostering decision pack.
Contributing (editors)
- Pages are markdown in the
knowledge-os-vaultgit repo (GitLabaspire/knowledge-os-vault).
Edit in Obsidian (preferred) or any editor.
- Follow style-guide — frontmatter required, 4 sections
(Context / Detail / Actions / Provenance), cite sources[], Mermaid for diagrams (never ASCII art).
- Push to
main. CI runs a generator smoke test, then rebuilds the HTML.
The site itself currently needs a manual Coolify redeploy of the ko-docs app to go live — ask Kom or an agent until the auto-deploy webhook is added.
- Not sure where a page goes? Put it in
_inbox/withstatus: draft.
Ingesting raw data (agents + power users)
| Data shape | Method |
|---|---|
| API/JSON | fetch → transform → .md table with sources[] |
| Long text (transcript, article) | python3 scripts/ingest_raw.py <file-or-url> --namespace X (engine repo; LLM-synthesises a lint-clean page — paid gateway call, get a per-run OK) |
| PDF/scans | KO ingest pipeline POST /ingest/upload (pending prod deploy) |
What does NOT go in the vault
- Secrets/credentials → Aspire Hub vault
- Individual-level staff data beyond name + role + team (no DOB, contact, pay)
- Live operational data that changes hourly (that belongs in dashboards)
- Raw text dumps — synthesise first; dumps pollute search
Actions
- New to a project? Read its
adg/projects/page first — diagram, status, open questions. - Spot something wrong or stale? Fix it (humans may edit freely) or flag
status: draft.
Provenance
Written 2026-06-11 summarising style-guide, the KNOWLEDGE_OS_SPEC (§16–17) and the live deployment of ko-docs.aspiredigital.group.
Related
- style-guide — the mechanical rules
- knowledge-os-stage-1 — the engine behind this
- labour-vs-sales — KO turning data into decisions