Migrate relevant context-vault documentation into docs/ #48

Open
opened 2026-11-07 20:26:50 +00:00 by martin · 3 comments
Owner

Summary

Move documentation relevant to this NixOS configuration from the context-vault repository into a repository-local docs/ directory. This repository should own its documentation without requiring a separate knowledge vault.

Scope

  • Inventory relevant architecture, operational procedures, patterns, and decisions in context-vault.
  • Review and migrate relevant material into docs/, retaining useful context and source attribution.
  • Add a documentation index and update discovery links and references.

Out of scope

Do not delete unrelated context-vault material or remove the source repository. Removing the context-vault skill and command is tracked separately in #49.

Acceptance criteria

  • Inventory context-vault documentation relevant to this repository, including architecture, operational procedures, patterns, and decisions.
  • Review selected content for accuracy, duplication, and outdated information; migrate only relevant material.
  • Organize the migrated documentation under docs/, retaining useful context and source attribution where appropriate.
  • Add a documentation index and links from README.md and AGENTS.md so people and coding agents can discover it.
  • Update references to the migrated material to use repository-local paths.
  • Check links and Markdown formatting, and confirm no credentials or secret values are copied.

Dependencies

  • Enables #49: the documentation migration must finish before the context-vault skill and command are removed.
## Summary Move documentation relevant to this NixOS configuration from the `context-vault` repository into a repository-local `docs/` directory. This repository should own its documentation without requiring a separate knowledge vault. ## Scope - Inventory relevant architecture, operational procedures, patterns, and decisions in context-vault. - Review and migrate relevant material into docs/, retaining useful context and source attribution. - Add a documentation index and update discovery links and references. ## Out of scope Do not delete unrelated context-vault material or remove the source repository. Removing the context-vault skill and command is tracked separately in #49. ## Acceptance criteria - [ ] Inventory context-vault documentation relevant to this repository, including architecture, operational procedures, patterns, and decisions. - [ ] Review selected content for accuracy, duplication, and outdated information; migrate only relevant material. - [ ] Organize the migrated documentation under `docs/`, retaining useful context and source attribution where appropriate. - [ ] Add a documentation index and links from `README.md` and `AGENTS.md` so people and coding agents can discover it. - [ ] Update references to the migrated material to use repository-local paths. - [ ] Check links and Markdown formatting, and confirm no credentials or secret values are copied. ## Dependencies - Enables #49: the documentation migration must finish before the context-vault skill and command are removed.
Author
Owner

Progress

Completed the initial copy-first migration in the local working tree, following the user's direction to review and change documentation afterward.

  • Copied 26 Markdown files into docs/: 12 from projects/nixos/, 6 from projects/martials-network/, and 8 relevant shared patterns. Preserved contents, frontmatter, filenames, and original directory structure byte-for-byte.
  • Added docs/README.md with a complete index and source attribution to context-vault revision f84e5856c78d21ca0e810b0f291e2decb5b42c9c.
  • Linked the index from root README.md and AGENTS.md, noting that copied material awaits review and does not override current configuration or agent guidance.
  • Left the source vault, context-vault skill, command, and permissions unchanged.

Validation

  • cmp verified all 26 copied documents match their source files byte-for-byte.
  • Validated 32 local links in the new index and root discovery documents.
  • nix fmt -- docs/README.md passed with no changes. Copied files were deliberately not reformatted.
  • git diff --check passed.
  • A limited scan of copied Markdown found no private-key, age-secret-key, GitHub token, or AWS access-key markers; no encrypted or decrypted secret files were accessed. This is not a comprehensive secret audit.

Decisions

This is a preservation pass, not completion of every acceptance criterion. Content accuracy, duplication, stale paths/cross-references, and copied Markdown formatting remain for the subsequent review. Changes are uncommitted; no configuration was built or activated. Keep #48 open and #49 blocked until that review is complete.

## Progress Completed the initial copy-first migration in the local working tree, following the user's direction to review and change documentation afterward. - Copied 26 Markdown files into `docs/`: 12 from `projects/nixos/`, 6 from `projects/martials-network/`, and 8 relevant shared patterns. Preserved contents, frontmatter, filenames, and original directory structure byte-for-byte. - Added `docs/README.md` with a complete index and source attribution to context-vault revision `f84e5856c78d21ca0e810b0f291e2decb5b42c9c`. - Linked the index from root `README.md` and `AGENTS.md`, noting that copied material awaits review and does not override current configuration or agent guidance. - Left the source vault, context-vault skill, command, and permissions unchanged. ## Validation - `cmp` verified all 26 copied documents match their source files byte-for-byte. - Validated 32 local links in the new index and root discovery documents. - `nix fmt -- docs/README.md` passed with no changes. Copied files were deliberately not reformatted. - `git diff --check` passed. - A limited scan of copied Markdown found no private-key, age-secret-key, GitHub token, or AWS access-key markers; no encrypted or decrypted secret files were accessed. This is not a comprehensive secret audit. ## Decisions This is a preservation pass, not completion of every acceptance criterion. Content accuracy, duplication, stale paths/cross-references, and copied Markdown formatting remain for the subsequent review. Changes are uncommitted; no configuration was built or activated. Keep #48 open and #49 blocked until that review is complete.
martin self-assigned this 2026-11-08 20:52:33 +00:00
Author
Owner

Metadata validation and normalization are complete for the 26 migrated documents.

Results

  • 26/26 documents parse as valid YAML frontmatter; no duplicate keys.
  • Category values normalized to the vault's plural convention: architecture=9, patterns=7, errors=6, learnings=3, decisions=1. No invalid values remain.
  • Every document now has a related key.
  • 104 resolvable related edges; 0 non-reciprocal edges (backlinks added).
  • 6 related entries still point to documents that were not copied: shell-script-best-practices.md, nix-flake-multi-binary-discovery.md, nix-import-tree-pattern.md, and three woodpecker-extension/cluster project docs. These exist in the source vault and are now documented as known unresolved pointers in docs/README.md.
  • Fixed a broken relative path in docs/projects/nixos/config/architecture.md and a bad patterns path in the Renovate error doc.
  • Inherited created/updated dates were left unchanged because document bodies were not revised.

Preservation check

All 26 copied files still have byte-identical bodies to context-vault revision f84e585; only frontmatter changed. nix fmt -- docs made no further changes and git diff --check is clean.

Content review and deciding whether to migrate the six referenced vault documents remain open. Nothing has been committed or activated.

Metadata validation and normalization are complete for the 26 migrated documents. ## Results - 26/26 documents parse as valid YAML frontmatter; no duplicate keys. - Category values normalized to the vault's plural convention: `architecture=9`, `patterns=7`, `errors=6`, `learnings=3`, `decisions=1`. No invalid values remain. - Every document now has a `related` key. - 104 resolvable `related` edges; 0 non-reciprocal edges (backlinks added). - 6 `related` entries still point to documents that were not copied: `shell-script-best-practices.md`, `nix-flake-multi-binary-discovery.md`, `nix-import-tree-pattern.md`, and three `woodpecker-extension`/`cluster` project docs. These exist in the source vault and are now documented as known unresolved pointers in `docs/README.md`. - Fixed a broken relative path in `docs/projects/nixos/config/architecture.md` and a bad `patterns` path in the Renovate error doc. - Inherited `created`/`updated` dates were left unchanged because document bodies were not revised. ## Preservation check All 26 copied files still have byte-identical bodies to context-vault revision `f84e585`; only frontmatter changed. `nix fmt -- docs` made no further changes and `git diff --check` is clean. Content review and deciding whether to migrate the six referenced vault documents remain open. Nothing has been committed or activated.
Author
Owner

Opened #54 as a WIP pull request for the migration: WIP: docs: migrate context-vault documentation.

It contains the 26 copied documents, the documentation index, the README/AGENTS links, and the metadata normalization. Content review and the six unresolved vault references remain before it is ready to merge.

Opened #54 as a WIP pull request for the migration: `WIP: docs: migrate context-vault documentation`. It contains the 26 copied documents, the documentation index, the README/AGENTS links, and the metadata normalization. Content review and the six unresolved vault references remain before it is ready to merge.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
Personal/nixos-configuration#48
No description provided.