feat: docs/ carries the operator's how-to guides, a configuration reference and the architecture and telemetry explanations carved out of README.md, INSTALL.md, INSTALL-MCP.md and EVALS.md; the last two retired (#190)
Files changed: - .gitea/workflows/ci.yml - .gitignore - .vibe/hooks.toml - AGENTS.md - CHANGES.md - EVALS.md - INSTALL-MCP.md - INSTALL.md - README.md - VERSION - docs/dev/development.md - docs/explanation/README.md - docs/explanation/architecture.md - docs/explanation/language-boundaries.md - docs/explanation/telemetry-and-evaluation.md - docs/how-to/README.md - docs/how-to/browse-with-obsidian.md - docs/how-to/capture-repository-docs.md - docs/how-to/export-guidelines.md - docs/how-to/ingest-a-source.md - docs/how-to/maintain-the-wiki.md - docs/how-to/query-the-wiki.md - docs/how-to/run-the-weekly-review.md - docs/how-to/set-up-the-mcp-server.md - docs/how-to/trace-and-score-sessions.md - docs/how-to/troubleshoot.md - docs/how-to/update-an-instance.md - docs/reference/README.md - docs/reference/commands/distribution-and-versioning.md - docs/reference/commands/instance-health.md - docs/reference/commands/raw-material-and-uploads.md - docs/reference/commands/telemetry.md - docs/reference/commands/types-instructions-and-docs.md - docs/reference/configuration.md - instructions/dev/dev-setup.md - instructions/dev/doc-pull-through.md - instructions/dev/stack-build/SKILL.md - instructions/dev/testing-conventions.md - instructions/dev/version-parts.md - instructions/setup-instance.md - instructions/upgrade-instance.md - reports/CONTRACT.md - tools/.coveragerc - tools/CONTRACT.md - tools/README.md - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/doctor.py - tools/chemenu/commands/eval_cmd.py - tools/chemenu/commands/git_publish.py - tools/chemenu/commands/upload_cmd.py - tools/chemenu/commands/version_cmd.py - tools/chemenu/evals/__init__.py - tools/chemenu/evals/scorecard.py - tools/chemenu/evals/trajectory.py - tools/chemenu/telemetry/policy.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_git_publish.py - tools/chemenu/tests/test_instructions_shell.py - tools/chemenu/tests/test_pipeline_l0.py - tools/chemenu/toc.py Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
This commit is contained in:
1 parent
cff7df4ffa
commit
f9056c04f7
61 files changed
+2169
-1772
No files matched your search
@@ -0,0 +1,59 @@
|
||||
# Capture documentation from a git repository
|
||||
|
||||
Documentation that lives in a git repository is captured, not copied by hand. A capture records the
|
||||
repository, the ref rule and the commit it came from. Later, the wiki can tell which captured
|
||||
material has fallen behind its repository, and take in the new edition as a whole.
|
||||
|
||||
## What you prepare
|
||||
|
||||
Access to the repository from this machine. Git uses your own keys and credential helpers, and
|
||||
nothing is stored in the instance. Then decide three things:
|
||||
|
||||
- the repository URL;
|
||||
- the ref to follow, usually a branch such as `main`;
|
||||
- which files count, as a glob, for example `docs/**/*.md`.
|
||||
|
||||
## Taking a repository in for the first time
|
||||
|
||||
You can run the capture yourself, or name the three values to the agent and let it run the
|
||||
command:
|
||||
|
||||
```bash
|
||||
tools/wikitool raw capture <repo-url> --ref main --path 'docs/**/*.md' --name <bundle>
|
||||
```
|
||||
|
||||
This writes the matching files, byte for byte, into `incoming/<bundle>/`, together with a
|
||||
`_capture.json` manifest naming the repository, the ref rule and the commit. From there it is an
|
||||
ordinary source: `Ingest incoming/<bundle>` ([Ingest a source](ingest-a-source.md)), with the same
|
||||
questions and the same gate.
|
||||
|
||||
## Keeping it current
|
||||
|
||||
```bash
|
||||
tools/wikitool raw status
|
||||
```
|
||||
|
||||
This lists every captured bundle that has fallen behind its repository, file by file, marking each
|
||||
file as added, modified or deleted. It only reads.
|
||||
|
||||
To bring them in, say:
|
||||
|
||||
```text
|
||||
Update the captured repositories
|
||||
```
|
||||
|
||||
The agent checks every captured bundle. It takes one changed bundle per run into the wiki, replacing
|
||||
the old edition as a whole, and tells you how many are still behind. Run it again for the next one.
|
||||
`raw capture --update` and `raw accept --replaces-bundle` are the commands underneath. What each one
|
||||
does is in the [command reference](../reference/commands/raw-material-and-uploads.md).
|
||||
|
||||
## Where the agent stops
|
||||
|
||||
The same places as any ingest: the `fidelity`/`authority` questions, the discussion of what
|
||||
matters, and the Mass-Update Gate when it publishes. When one repository cannot be reached, the
|
||||
agent reports the error and carries on with the others. A failure in one never stops the run.
|
||||
|
||||
## Related
|
||||
|
||||
- [Export guidelines](export-guidelines.md) - sending the wiki's guidelines back into the same
|
||||
repositories.
|
||||
Reference in new issue
Block a user