docs(customization): add project knowledge base bootstrap recipe

[chris-buckley]

Description

Adds a docs-only how-to recipe for bootstrapping a project knowledge base: a
source-backed, repository-shaped memory for a project, engagement, product, or
workstream, kept as a separate repository and referenced from one or more
working repositories.

The page covers what a project KB is and when to use one, the
separate-repository model, a starter taxonomy (project, people, organizations,
systems, concepts, events, decisions, risks, deliverables, assets), the
event-to-entity update loop that keeps it current, how to point Copilot at
the KB with an instructions file, and maintenance guardrails for stale facts,
conflicting concepts, and misplaced files.

Follows from Discussion #1250 and the docs-first scope agreed on the issue.
Placement under docs/customization/ per the issue; happy to move it if
maintainers prefer another home.

Files changed:

• docs/customization/project-knowledge-base.md (new)
• docs/customization/README.md (File Index entry added, ms.date bump)

Related Issue(s)

Closes #1862

Type of Change

Code & Documentation:

• Documentation update

Testing

Docs-only change. Relying on the PR validation pipeline for markdown lint,
spell check, frontmatter, and link checks; will address any findings. Content
was checked by hand against the frontmatter, style, and table conventions of
the existing docs/customization/ pages.

Checklist

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (not applicable, docs only)

Required Local Checks

• Local validation aggregate: npm run validate:local
• Documentation validation (if docs changed): npm run validate:docs
• Spell checking: npm run spell-check
• Link validation: npm run lint:md-links

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues (none added)
• Security-related scripts follow the principle of least privilege (not applicable)

[Codecov Comments Bot (codecov-commenter)]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.74%. Comparing base (0282ade) to head (1056dbe).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2546      +/-   ##
==========================================
- Coverage   82.75%   82.74%   -0.01%     
==========================================
  Files         155      155              
  Lines       20960    20960              
  Branches       13       13              
==========================================
- Hits        17345    17344       -1     
- Misses       3613     3614       +1     
  Partials        2        2              

Flag	Coverage Δ
docusaurus	94.44% <ø> (ø)
pester	86.18% <ø> (-0.02%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Nikolai Maksimov (nikolaimak)]

This is excellent guidance for a single-project KBs. For teams running multiple projects from one KB, I'd add two patterns: strict upstream-only lifecycle sync + deterministic scripts to prevent drift, and (2) dual-access layers—semantic search for agents and Obsidian-style graph navigation for humans. These ideas are coming from my experience maintaining a KB for the personal use.

1. It works well if the whole knowledge base is for one project, if there are more than 1, the lifecycle fields of a project start drifting very fast - because the KB is not a project management system. Possible mitigations:

• have really strict policy about updating the relevant fields automatically only from the upstream (e.g. AzDevops)
• use determenistic scripts to maintain these data
• store as little as possible about the LifeCycle of the project in the KB

2. KB can be useful both for agents and for humans:

• agents can access it with a semantic search tool over the .md files - like it is organized in OpenClaw - in my case I've added the KB to the index as an additional source. It will get needed once the KB becomes too big.
• humans can query the kb via data, or browse the folder in the repo directly. Additionally, they might benefit from organizing the knowledge as an obsidian vault - it is achieved by adding a frontmatter to each entity, and index files. Then they can use Obsidian as a frontend to view the KB and query/visualize it in interesting ways. For instance, here is how the Scout dev team organized it.

[Jamie Kim (jkim323)]

Apologies on the delay for getting to this... First off, much appreciate for this — the taxonomy and the event-to-entity update loop are the parts I find most useful, and I agree that the separate-repository model is a strong foundation.

I have two areas I’d like to understand better as we discuss this, neither of which is about the quality of the writing.

First: how should we think about what a docs page asserts? team-adoption.md has a maturity ladder — experimental, preview, stable — but it applies to artifacts through x-hve.componentMaturity. We do not seem to have an equivalent vocabulary for practices. That makes me curious how we want readers to interpret a page like this: as established guidance, a pattern that has worked in particular contexts, or something in between.

This feels like a broader repository question rather than something specific to this PR, but this contribution may be a useful example through which to explore it.

Second: what has the evidence base looked like in practice? Nikolai Maksimov (@nikolaimak)’s point about lifecycle drift gets at the shape of what I’m trying to understand. The pattern may have a narrower boundary than the page suggests, and I’d be interested in learning more about that boundary:

• How many projects has this been used on, and over what period?
• Did the ten-entity taxonomy emerge from usage, or was it designed up front? Which categories proved durable?
• How has maintenance worked in practice? Knowledge bases often become less useful through staleness rather than incorrectness, so I’m particularly curious whether the described update loop has held up over time.
• Where have you found the line between durable context that belongs in the KB and mutable lifecycle state that should remain in an upstream system?

I’m mostly curious to understand the experience that informed the pattern: where it has worked especially well, what conditions made it effective, and where its boundaries or limitations have become clearer in practice. Thanks!

[Katrien De Graeve (katriendg)]

Thanks for this work chris-buckley.

Overall, I support merging this contribution after comment resolution and conflict cleanup.

I think the PR addresses a real problem: teams need durable, discoverable project context that can be consumed by both humans and agents. The examples and workflow provide a very useful starting point for exploring that pattern without being too prescriptive.
HVE Core itself IS opinionated so it's essentially OK to be prescriptive, but given the level of experimenting on this domain, I would remove some of the level of prescription.

At this stage, I would prefer we position this as an experimental or emerging customization pattern rather than an official HVE Core recommendation. We do not yet have sufficient evidence that a specific repository structure, knowledge-base layout, or operating model is broadly applicable across all teams and customer environments.

Suggested direction:

• Merge as an experimental/project customization example.
• Emphasize the outcome (durable project knowledge) rather than the implementation (specific repository structures or storage models). I believe it's still something teams may have their own solutions for, having a suggestion is a great way to start but we should leave it open ended.
• Reduce assumptions that users will have dedicated knowledge repositories.
• Keep examples simple and source-backed.

I believe this gives users something immediately valuable while preserving room for future evolution as we learn more from real-world adoption, as we keep learning with HVE Core and our projects.

[Katrien De Graeve (katriendg)]

Based on the early approach we are looking for testing and evolving, suggest naming this Experimental Project Knowledge Base Bootstrap Recipe, so it's clear it's not the proven HVE Core approach but a first iteration.

[Katrien De Graeve (katriendg)]

Suggest to add a disclaimer on the intro so that users clearly see this area is emerging and not fully defined.

This recipe represents an emerging pattern observed across several agentic engineering teams. It is provided as an example for experimentation and learning, not as a required HVE Core architecture.