4.9 KiB
name, description
| name | description |
|---|---|
| homelab-knowledge | Query and maintain the shared homelab-wiki when working on homelab services, infrastructure, architecture, operations, or current service status. Use it to gather existing context before work and to keep durable knowledge synchronized after relevant changes; do not use it for unrelated software work or as a substitute for commit and PR history. |
Homelab Knowledge
Use homelab-wiki as the shared long-lived knowledge base for people and agents. Search it directly with rg; do not introduce a search index, vector database, or generated copy of the wiki.
Locate the wiki
Resolve the checkout in this order:
$HOMELAB_WIKI_PATH, when set.- A sibling directory named
homelab-wikinext to the current repository. /home/panxiao81/homelab-wikiwhen it exists.
If no checkout is available, report that constraint. Do not silently skip the knowledge step, clone a repository, or create a replacement wiki without the user's authorization.
Before using the wiki, read its AGENTS.md completely. For edits, also read README.md and CONTRIBUTING.md completely and follow any more specific instructions associated with the target page.
Gather context
At the beginning of a homelab task:
- Derive search terms from the component name, service aliases, hostnames, Kubernetes resources, configuration keys, error text, and task intent.
- Use
rg -n -iin the wiki to find candidate pages. Prefer several precise searches over reading the whole repository. - Follow the wiki's task index, service index, architecture constraints, source records, and verification conflicts when they are relevant.
- Read the closest authoritative pages and their material links before making decisions. Also read the corresponding source repository README or runbook when changing an implementation.
- Distinguish documented design, declared configuration, deployment history, live verification, and work currently in progress. Do not present one as another.
For questions about current project or service status, first obtain the maintainer's current-work and ticket context as required by the wiki, unless the conversation already provides that authorization and scope. Reading documentation does not authorize live-system inspection.
Answer read-only questions from the evidence found. Include paths or links that let the user verify important claims, and state when evidence may be stale or conflicting.
Maintain knowledge after changes
For any code, configuration, infrastructure, or operational change, perform a documentation-impact check before declaring the task complete.
Update the wiki in the same task when the change affects durable knowledge such as:
- service purpose, lifecycle, entry point, authentication, permissions, dependencies, or first-use path;
- architecture boundaries or accepted constraints;
- deployment ownership or persistent operating behavior;
- troubleshooting, recovery, verification, or maintenance procedures;
- the addition, replacement, or retirement of a service.
Keep one-time progress, implementation narration, and release-by-release history in commits, PRs, or tickets. Do not copy them into the wiki unless they change a durable stage summary. Implementation-specific parameters may remain in the source repository README or runbook when the wiki convention says to link rather than duplicate them.
When editing:
- Inspect both the source-repository diff and the wiki working tree before writing. Preserve unrelated user changes in both repositories.
- Update the page closest to the fact first, then only the navigation, indexes, constraints, or verification records that the wiki rules require.
- Preserve evidence metadata. Never advance
last_verifiedwithout performing the stated live verification; ordinary review may update only fields permitted by the wiki. - Link related source commits, PRs, or paths when available. Clearly mark uncommitted sources and unfinished cross-repository synchronization.
- Record conflicts rather than resolving them by assumption. Ask before live inspection or before choosing among materially conflicting current-state claims.
- Keep credentials, tokens, private keys, Terraform state, secret values, and sensitive command output out of documentation. Never read or copy known sensitive files merely to improve the wiki.
Wiki edits are a separate repository change. Do not commit, push, open a PR, or modify a live system unless the user has authorized that action.
Verify and report
After editing the wiki, run from its root:
python3 scripts/check_docs.py
git diff --check
If the checker itself changed, also run:
python3 -m unittest discover -s tests -v
In the final response, report source-repository changes and wiki changes separately, including validation performed and anything still awaiting verification or cross-repository linkage. If no wiki update was needed, state the concrete reason; do not merely say that documentation was unaffected.