docs/README.md

Table Of Contents

1. Using These Docs
   1. What Lives Here
   2. Reading Map
   3. Repository Terms
2. Documentation Standards
   1. Heading Structure
   2. Markdown Formatting Rules
   3. GitHub Callouts
   4. Link And Backlink Rules
   5. Static Figure Rules

1. Using These Docs

What Lives Here

This directory is the GitHub-rendered manual for kneifftools. The root README stays short enough for installation and first use. These files hold longer task recipes, maintainer workflow, exact references, and conceptual explanations.

Fig. 1 - Documentation Reading Map: Start at the root README, then move into the docs file that matches the job: recipe, maintainer workflow, exact names, or system model.

Related: use How-To User Guides for commands in order, References for exact names, and Explanations for why the project behaves as it does.

Reading Map

• How-To User Guides: task recipes for install, first run, dataset sync, LoRA, image utilities, and troubleshooting.
• Development: maintainer setup, repository routing, implementation standards, docs authoring, verification, and commit checks.
• References: exact paths, commands, environment variables, config files, public interfaces, and figure visual tokens.
• Explanations: package layout, manifest/export model, caption sidecar model, LoRA flow, image utility model, and failure model.

The first reading path is:

1. Use the root README for the shortest setup route.
2. Use How-To User Guides for commands in order.
3. Use References when you need exact names.
4. Use Explanations when you need the system model.
5. Use Development before changing source files.

Repository Terms

Use these terms the same way in every docs file:

Term	Meaning	Main Reference
repository root	The Kneiff source checkout that contains pyproject.toml, README.md, and src.	References: project paths
package source	The importable Python package under src/kneiff.	References: project paths
maintainer environment	The local development environment with dependency groups installed.	Development: maintainer loop
runtime dependency	A dependency needed by users of the installed package.	Explanations: dependency model
development dependency	A dependency used for tests, linting, typing, docs, profiling, or local tooling.	References: dependency surfaces
project root	The AppRC-selected Kneiff scaffold containing root vocabulary/prompt overlays, default_tags.txt, .env.apprc-storage, project Git files, configs/ANIMA.knf.yaml, configs/F2K_9B.knf.yaml, starter SOURCE/ folders, ignored HF//TRAINING/ directories, MANIFEST.knf.xlsx, and generated MANIFEST.yaml.	Explanations: manifest-to-export model

2. Documentation Standards

Heading Structure

Long docs files may use multiple # headings. Use them for major document parts, not only for the file title. The table of contents must mirror the real structure so a reader can tell which sections are sequences, which sections are tool groups, and which sections are independent references.

Use this hierarchy:

Level	Use
#	Major document parts, for example First-Time Setup, Common Workflows, or Failure Model.
##	Recipes or concept chapters inside a major part.
###	Ordered substeps inside a large recipe.

Avoid a flat file where every section is a ## peer. A long sequence should be one recipe with substeps, not a cluster of unrelated recipes.

Markdown Formatting Rules

• Start every major docs file with a compact table of contents.
• Make the ToC match the heading hierarchy.
• Use the repository terms from Repository Terms.
• Use exact technical names: source paths, environment variables, CLI commands, config attributes, and file names.
• Avoid generic advice such as "check settings"; say which value to inspect, for example KNF_WORKERS, configs/*.knf.yaml, MANIFEST.knf.xlsx, or generated MANIFEST.yaml.
• Use separator comments before major sections:

<!-- ======================================================== -->
## Section Title
<!-- ======================================================== -->

• Use centralized reference links near the bottom of a file when a link is reused:

<!-- --- URLs --------------------------------------------------- -->
[`uv`]: https://github.com/astral-sh/uv

• Use <details> dropdowns for long examples inside procedural docs:

<details><summary> <u> <i> Longer command sequence </i> </u> </summary>
<blockquote>

```bash
knf dataset sync example.knf.yaml
knf train prepare example.knf.yaml
```

</blockquote></details>

GitHub Callouts

Use callouts to mark the job a paragraph does. GitHub renders only the fixed labels TIP, NOTE, IMPORTANT, WARNING, and CAUTION; text after the marker is not rendered as a custom title.

Callout Syntax

> [!TIP]
> Explanation text goes here.
>
> ```bash
> knf --help
> ```

Callout Types

Optional advice that improves speed, clarity, or workflow.

Helpful context that is not required to complete the task.

Required prerequisites, environment variables, version constraints, or architecture rules.

Risks, deprecated behavior, high-cost operations, or temporary bugs.

Destructive or security-relevant actions.

Link And Backlink Rules

• Prefer relative links.
• Link to exact chapters when the target section matters.
• Use [!NOTE] callouts for return links from concept and reference sections.
• Start one-line related-link callouts with Related:.
• Start multi-link related-link callouts with Related links:.
• Add a short purpose phrase for every related link so the reader knows why it matters.
• Do not use standalone backlink labels in prose.
• Add return links from explanations to the relevant how-to recipes and references.
• Add reference links from recipes when exact paths, config keys, or environment variables matter.
• Link to source files directly when a user may need to edit the file.
• After moving docs, check file links, image links, and local anchors together.

Static Figure Rules

Docs figure assets live in assets. Their repository-owned source is render_figures.py, which defines the local Graphviz theme, node contract, and rendering pipeline. Add more figures only when a diagram makes the prose easier to understand.

Figure rules:

1. Change docs/render_figures.py, then regenerate assets with just docs-figures.
2. Keep the generated canvas transparent.
3. Keep black text on a readable surface fill so GitHub dark mode remains legible.
4. Use semantic strokes from FigureTheme and match each edge to its target node color.
5. Use Figure Visual Tokens before choosing or changing local theme values.
6. Embed SVG files in Markdown with a centered table:

| ![Alt text](assets/example.svg) |
|:--:|
| **Fig. N - Figure Title:** Caption sentence. |

Related links:

• Use References: figure visual tokens for the repository-owned figure theme source of truth.
• Use Development: documentation authoring before expanding the docs structure or adding new figure assets.