BoK Manual

Cozy BoK source and site operation manual.

Dashboard

This manual describes the standard BoK operation workflow and responsibilities. Project-local rules belong in repository documentation.

Quick Links

Basic Operations

  • cozy bok create --save <dir>: Create a BoK source scaffold.
  • cozy bok create-category <name> --project <dir>: Add a category dashboard, article seed, and term seed.
  • cozy bok doctor <dir>: Inspect the BoK source tree.
  • cozy bok build <dir> --strategy preview: Generate website.d through SmartDox and Antora.
  • cozy bok preview <dir> --port <port>: Serve generated website.d through a local Web server.
  • cozy bok publish <dir> --dry-run: Verify the publication plan and side-effect boundary.

Source Document Formats

BoK source documents can be written in GitHub Markdown or SmartDox. GitHub Markdown is recommended for general Knowledge Contributors because it keeps ordinary article authoring close to GitHub editing, review, and Pull Request workflows.

SmartDox is recommended for advanced contributors who need the full BoK feature set: BoK metadata, glossary linkage, RDF linkage, and SmartDox-specific structured authoring.

Multilingual BoK authoring is SmartDox-only. GitHub Markdown is treated as the normal single-language article format.

Glossary Term Classification

Term classification starts from unclassified candidates, uses mono/koto as an analysis aid, and then assigns a term type based on the term's role in the BoK knowledge space.

  1. Review unclassified terms.
  2. Check articles, scenarios, bibliography, and Project/CML metadata to understand the term's role.
  3. For existence-like terms, choose concept, entity, actor, role, resource, or artifact.
  4. For terms that happen, are performed, change, or control decisions, choose event, action, process, task, rule, state, or scenario.
  5. Keep uncertain candidates unclassified until evidence, related articles, or related terms are clearer.
  6. After classification, verify definition, related articles, RDF links, and Project/CML links in the Term Hub.

Actor Operations

BoK operation separates responsibilities among Knowledge Contributors, BoK Managers, and Site Administrators. A Knowledge Contributor is the Knowledge Owner for some knowledge. For knowledge they own, they edit Git source and push a branch. For knowledge they do not own, they propose changes through a Pull Request. BoK Managers and Site Administrators use Pull Requests as the review, merge, and publication decision boundary.

Knowledge Contributor

  1. Edit Git source for knowledge they own, such as articles, terms, categories, media, and publication records.
  2. For knowledge they do not own, prepare the change on a working branch and propose it through a Pull Request.
  3. Run cozy bok doctor to check structure, metadata, links, terms, and RDF basics.
  4. Run cozy bok build --strategy preview and cozy bok preview to verify dashboards, category pages, glossary, term hub, RDF graph, and recent changes.
  5. Commit and push the working branch.
  6. Open a Pull Request when ownership review, BoK Manager review, or publication review is needed.

BoK Manager

  1. Review Pull Requests for content, structure, terms, RDF, and consistency.
  2. Request fixes in the Pull Request when needed, then merge approved changes into main.
  3. Run cozy bok publish --dry-run to verify the publication plan.
  4. Pass only consistent, high-quality knowledge to the publication flow.

Site Administrator

  1. Manage hosting, upload settings, secrets, and access control.
  2. Operate stage/upload workflows after the publication change is reviewable through Pull Requests.
  3. Handle monitoring, backups, incident response, and cache invalidation.

Source / Generated Boundary

Knowledge Contributors edit Git source only. They maintain knowledge they own directly and propose changes to knowledge they do not own through Pull Requests.

Editable Source

  • src/main/doxsite/**/*.dox
  • src/main/doxsite/**/*.md
  • src/main/doxsite/**/category.yaml
  • src/main/doxsite/glossary/**/*.dox
  • src/main/media/** for durable article-media inputs
  • src/main/publication/** for the durable publication registry
  • src/main/extensions/rdf/** only for explicit admitted non-derived declarations

Do Not Edit Generated Artifacts

  • website.d/
  • doxsite.d/
  • antora.d/
  • target/
  • repository/

The standard Manual, History dashboard, RDF, machine metadata, and UI are generated outputs; they are never edited as source.

Page Types

  • Home: whole-BoK dashboard.
  • Category Dashboard: category-local KPI, articles, terms, and operation notes.
  • Glossary: BoK-wide vocabulary dashboard.
  • History: BoK operation and publication history dashboard.
  • Manual: BoK operation entry point.

Operation Notes

Standard BoK pages are dashboards, not ordinary articles. Glossary, History, and Manual are BoK console pages rather than normal categories. Manual pages are excluded from automatic glossary linking.