# Maintenance Workflow

Use this reference when updating the skill, adding manuals, refreshing official Xinje document metadata, or converting repeated problems into reusable knowledge.

This skill does not train itself in the background. Treat "self-learning" as a disciplined maintenance loop: record repeated failures, add scripts or references, validate, and update the working skill. Build a share `.zip` only when the user explicitly asks for a package.

## Update Loop

1. Identify the gap from a real user question or failed answer.
2. Check `xinje-official-document-catalog.md` and the full CSV/JSON catalog before downloading files.
3. Prefer official Xinje sources. Record source URL, file ID, title, version, update date, page count, and local path.
4. If a new PDF is downloaded, create a full-manual overview before bundling it:
   - metadata and official provenance,
   - table of contents / chapter map,
   - page-count and important page ranges,
   - task-oriented summary for the user's immediate need,
   - coverage-map entry that states exactly what is and is not distilled.
5. Convert repeated operational problems into `known-ingestion-issues.md`.
6. Add or improve scripts when the same command sequence is repeated.
7. Update `SKILL.md` reference map only with stable, high-value routes.
8. Run the validator before installing, sharing, or treating the working copy as ready.
9. Do not rebuild the `.zip` share package after every edit. Rebuild it only when the user explicitly asks to package/share the current skill, then choose the version number from the accumulated changes.

## Git Release Rule

The Git repository is the release history for this skill. After every completed content, script, index, or source-coverage change:

1. Validate the changed skill content and review `git status`.
2. Run `pwsh -File scripts/release_skill.ps1` from the repository root.
3. The script increments the `SKILL.md` version by `0.1` (`1.5.0` -> `1.6.0` -> `1.7.0`), stages the complete skill change set, creates a release commit, and pushes the current branch to `origin`.
4. Report the resulting version and commit hash. If push fails because authentication or network access is unavailable, keep the commit and report the exact blocker; retry the push before starting unrelated maintenance.

Do not run the release script when no skill files changed. A Git release does not imply a ZIP package: build the ZIP only when the user explicitly requests it.

## Coverage Levels

Use these labels in `coverage-map.md`:

- `cataloged`: official metadata is known; file is not downloaded.
- `downloaded`: source file is bundled, but not summarized enough to rely on directly.
- `overview`: full-manual table of contents and chapter map are distilled.
- `focused`: one or more task-oriented references are distilled for common workflows.
- `detailed`: the relevant chapters are summarized deeply enough for normal answering.
- `complete`: the whole manual is summarized into navigable references with source coverage notes.

Do not call a PDF `complete` merely because it is bundled in `assets/manuals/`.

## Add-Manual Rule

When adding a new manual PDF to `assets/manuals/`, do these in the same skill version:

1. Add a row to `source-index.md`.
2. Add or update `coverage-map.md`.
3. Add at least one full-manual overview reference or a focused topic reference.
4. If the manual is large, split detailed coverage by chapter or task area instead of creating one huge Markdown file.
5. If full distillation cannot be completed in the same turn, keep the file out of `assets/manuals/` and leave it as `cataloged` until needed.

Useful scripts:

- `scripts/download_catalog_ids.py --catalog assets/catalogs/xinje-official-document-catalog.csv --output-dir assets/manuals --ids <id...>` downloads official catalog entries with stable filenames.
- `scripts/probe_pdf_manuals.py --manual-dir assets/manuals --output work/pdf_probe.md --pages 12` records page counts and frontmatter/table-of-contents text.
- `scripts/search_pdf_keywords.py <pdf> <keyword...>` locates page numbers before extracting a focused range.
- `scripts/extract_pdf_pages.py <pdf> <start-page> <end-page> <output-md>` extracts a focused page range into UTF-8 Markdown.
- `scripts/build_pdf_search_index.py --manual-dir assets/manuals --output-db assets/indexes/xinje-manual-fulltext.sqlite --output-toc-json assets/indexes/xinje-manual-toc.json --output-toc-md references/manual-chapter-index.md` builds the page-level full-text/TOC index after the manual set changes.
- `scripts/search_xinje_manuals.py --index assets/indexes/xinje-manual-fulltext.sqlite <query>` searches the index before falling back to a full PDF scan.

## Website Catalog Refresh

Run:

```powershell
& '<python.exe>' -X utf8 outputs\xinje-plc-programming\scripts\catalog_xinje_downloads.py --output-dir outputs\xinje-plc-programming\assets\catalogs
```

After refreshing:

1. Compare counts with `xinje-official-document-catalog.md`.
2. Check whether key PLC/HMI manuals have new versions or update dates.
3. Update `source-index.md` only for manuals actually bundled or used.
4. Avoid downloading new files just because they appear in the catalog.

## Answering With Unfinished Coverage

If a user asks about a topic whose manual exists but is not yet distilled:

1. Say the catalog has an official source.
2. Download only the needed official manual or page range.
3. Extract and summarize the relevant section.
4. Update the skill reference if the topic is likely to recur.
5. Mark coverage honestly; do not imply the whole manual has been learned.

## Post-1.2.0 Expansion

Use `future-expansion-plan.md` before downloading more files. The default next work is:

1. P2 motion/positioning/fieldbus manuals only when motion or fieldbus questions appear.
2. P3 controller-family manuals only when the user names XDQ/XLQ, XSF, XS/PLCopen, or XC migration.
3. P4 deeper Markdown distillation of already bundled manuals when repeated questions hit the same chapter.