The SelfDoc feed is the repeatable path from implementation evidence to manuals, diagrams, and public website pages. It exists so x64base and DotTalk++ can describe themselves without turning memory, chat notes, or website prose into technical truth.
Select the diagram to inspect the full-resolution evidence and promotion map. The feedback path is intentional: publication review can report drift, but corrections return to the owning source or metadata lane.
The doctrine is intentionally strict:
- runtime proves;
- source defines;
- HELP explains;
- metadata organizes;
- SelfDoc preserves;
- MDO curates;
- manualgen packages;
- the website publishes reviewed derivatives.
What The Feed Does
The feed gives every public technical claim a path back to evidence. A command page should not merely say that a command exists; it should be traceable to registration, HELP, usage contracts, source comments, command-reference harvests, runtime proof, or a reviewed manual section. A diagram should not be decorative; it should be attached to the same evidence spine as the text it explains.
This matters most for the surfaces that can drift quickly:
| Surface | Why It Needs The Feed |
|---|---|
| Commands and functions | Names, aliases, arguments, mutation behavior, and proof status change as the shell grows. |
| SET family and settings | Runtime defaults, scoped behavior, and command families need source-derived readback. |
| Data mutators | REPLACE, CALC, CALCWRITE, MULTIREP, import/export, commit, rollback, and table-buffer commands need explicit dirty/stale/risk labels. |
| File formats | DBF, VFP, MS-DOS, DBF_64, memo, and index claims must trace back to headers, readers, writers, probes, or specs. |
| Workspaces and areas | Workspace wrappers, dbarea behavior, relations, buffers, and cursor control are runtime concepts, not brochure claims. |
| Diagrams and screenshots | Visuals are curated artifacts; they need owners, attachment rows, and review state. |
Authority Order
The authority order is:
- Runtime/source behavior in
implementation checkout. - HELP, metadata, command registration, comments,
@dottalk.usage,@dottalk.contract, contract scans, and canary evidence. - SelfDoc reports and manualgen manifests.
- Reviewed manual sections.
- Website pages in
website source tree.
When a DotTalk++ command or function is added, the expected flow is:
source change
-> command/function registration
-> source header usage contracts and source comments
-> HELP / metadata / comments evidence / contract scans
-> SelfDoc and CMDHELPCHK validation
-> manualgen inventory / validate / dry-run
-> reviewed manual section
-> website command/function/API pages
The website is allowed to organize, summarize, and teach. It is not allowed to become the upstream authority for runtime behavior.
Feed Lanes
The current feed is not one monolithic generator. It is a set of lanes that should converge before public promotion.
| Lane | Inputs | Outputs | Promotion Gate |
|---|---|---|---|
| Source/runtime lane | C++ source, headers, build files, scripts, runtime transcripts, canaries | implementation facts, proof notes, smoke outcomes | Must be source- or runtime-evidenced. |
| Comments snapshot lane | Source comments, usage contracts, file identity, prior immutable snapshots | reharvest ledger, mutation comparison, unauthorized-drift findings | Snapshot generation is report-only; mutation or promotion requires review. |
| HELP lane | HELP, CMDHELP, CMDHELPCHK, command metadata, help tables | command descriptions, argument notes, missing-topic reports | Must preserve command identity and status. |
| Contract lane | @dottalk.usage, @dottalk.contract, comments, mutation labels | usage contracts, risk flags, public command safety notes | Mutating commands must say what they mutate. |
| SelfDoc lane | scanners, inventories, crosswalk builders, report-only probes | CSV/MD reports, feature crosswalks, candidate findings | Uncertain findings stay labeled. |
| MDO lane | organized report shelves, section maps, diagram ledgers | manual sections, publication decisions, attachment maps | MDO curates; it does not erase source uncertainty. |
| Manualgen lane | inventories, validate runs, dry-run builds, accepted sections | reviewed manuals and downloadable/manual-ready artifacts | Validate before publication; note environment limits. |
| Website lane | reviewed manual sections, evidence summaries, public media | x64base.com pages and diagrams | Publication derivative only. |
| Progress registry lane | accepted gate records, publication commits, benchmark state, separate mission backlog | human-readable progress page and machine-readable website metadata | Completed and pending states must never be collapsed into one claim. |
Current Report-Only Feed
The current repeatable feed uses report-only commands from the implementation checkout:
cd implementation checkout
python tools\manualgen\manualgen.py --repo-root implementation checkout --manual developer inventory
python tools\manualgen\manualgen.py --repo-root implementation checkout --manual developer validate
python tools\manualgen\manualgen.py --repo-root implementation checkout --manual developer build-dry-run
python tools\selfdoc\build_engine_feature_crosswalk.py --repo-root implementation checkout
Generated outputs include:
labtalk/reports/selfdoc/x64base_engine_feature_crosswalk_v1.csvlabtalk/reports/selfdoc/x64base_engine_feature_crosswalk_v1.mddocs/manuals/developer/generated/x64base_engine_feature_crosswalk_manual_section_v1.mddocs/manuals/developer/manualgen/generated/manualgen_build_dry_runs/<run>/developer_manual_build_dry_run.mddocs/manuals/developer/manualgen/reports/help-topic-to-manual-section-map-v1.csvdocs/manuals/developer/manualgen/reports/help-topic-to-website-section-map-v1.csvdocs/manuals/developer/manualgen/reports/shared-message-to-surface-map-v1.csvdocs/manuals/developer/manualgen/reports/diagram-publication-attachment-matrix-v1.csv
These outputs are evidence shelves. They are not automatically public copy.
Status Labels
Public pages should preserve status instead of smoothing it over.
| Label | Meaning |
|---|---|
| runtime-evidenced | Observed in a runtime transcript, smoke test, canary, or generated proof output. |
| source-evidenced | Found in source, headers, command registration, parser code, or build files. |
| help-catalog-evidenced | Present in HELP/CMDHELP/help-data/catalog surfaces. |
| manual-reviewed | Accepted into a reviewed manual section or manualgen lane. |
| generated-reviewed | Generated report or projection reviewed before publication. |
| planned | A real lane or design goal, but not implemented. |
| canary | Exists as a probe, experiment, or limited proof path. |
| review-needed | Scanner output or memory note found something that still needs human or runtime confirmation. |
Promotion Rules
- Do not auto-promote uncertain scanner output into public copy.
- Preserve status labels: runtime-evidenced, source-evidenced, help-catalog-evidenced, manual-reviewed, planned, canary, review-needed.
- Do not claim a lane is complete when the evidence says active beta, canary, or review-needed.
- Keep generated reports local until reviewed, then summarize them on the website.
- Command and function pages should cite the extraction snapshot and should be regenerated when HELP/CMDHELP/usage contracts change.
- Commands that launch external apps, perform network requests, write files,
write HELP DATA, or write DBFs must carry explicit
mutates:andrisk:fields before being promoted as stable docs. - Treat source/manual-to-website as the normal simplex flow. Treat website-to-manual as blocked unless the web artifact is separately maintained and not derivable from the implementation checkout.
- Treat
README.*files as sacred orientation artifacts. If a README must be replaced, preserve the previous version as a versioned artifact before promotion.
Procedural Curation
Select the diagram for a full-resolution inspection view. Each lane has a named responsibility, a durable artifact, and an explicit gate; no lane can silently promote its own output.
| Step | Owner | Durable Artifact | Required Gate |
|---|---|---|---|
| Collect | Source/runtime maintainer | Evidence snapshot, transcript, canary, or source citation | Behavior is observed or source-evidenced. |
| Explain | HELP and contract owner | Command identity, usage, mutation, and risk semantics | CMDHELPCHK and contract validation agree. |
| Normalize | Metadata curator | Registry row, alias/family mapping, status, and provenance | Identity is reconciled and uncertainty remains labeled. |
| Preserve | SelfDoc lane | Versioned report, crosswalk, proof link, or drift finding | Provenance is retained; scanner output is not auto-promoted. |
| Curate | MDO reviewer | Accept, defer, reject, and target-attachment decision | A human owner approves both claim and publication target. |
| Package | Manual and website maintainers | Reviewed section, diagram, page, and release metadata | Build, route checks, and public-content guard pass. |
The repeatable curation loop is:
scan source headers
-> harvest comments and usage contracts
-> rebuild or inspect HELP/CMDHELP surfaces
-> run CMDHELPCHK or report-only validators
-> run manualgen inventory/validate/dry-run
-> review generated sections
-> update website derivatives
CMDHELP, CMDHELPCHK, MAINT, DDICT, MANUAL, BBOX, and contract tools
all belong in this loop. Their documentation should state mutation boundaries
explicitly so a report-only inspection command does not get mistaken for a
promotion command.
Manual And Website Intake Gate
Manual generation should not scrape public website prose as a shortcut for technical truth. The website is a publication derivative; the manual should consume the same upstream evidence that fed the website whenever that evidence exists.
Allowed manual intake from the website is limited to artifacts that are:
- not derivable from source, HELP, metadata, SelfDoc, MDO, or manualgen;
- intentionally maintained as website/public artifacts; and
- labeled with provenance and owner.
Examples include curated screenshots, public navigation/framing copy, contact details, branding pages, hosted-download metadata, or a website-only media artifact. Runtime claims, command syntax, file-format claims, index behavior, data-mutator behavior, and engine feature claims must go back to the implementation checkout and generated evidence lanes.
Diagram Lane
Diagrams are not decoration. They are attached explanatory views over the same evidence spine.
Current rule:
prove or verify the lane
-> identify manual and website targets
-> attach a canonical diagram source
-> render/promote a website asset only after review
-> preserve the attachment row so the public image never becomes orphan truth
The current attachment ledger is:
docs/manuals/developer/manualgen/reports/diagram-publication-attachment-matrix-v1.csv
That ledger crosswalks canonical manual SVGs, LabTalk diagram sources, and promoted site image assets so the publication surface stays traceable.
Accepted 2026-07-18 Checkpoint
The governed manualgen run now uses Python 3.12.9; the earlier environment
limitation no longer describes the current publication. The accepted product
contains:
- 4,118 manual lines and 237 headings;
- 24 balanced sections and four appendices;
- 191 current command-reference pages: 164 reader-linked, 19 supplemental, and 8 post-baseline repair pages;
- 4,604 command lineage rows in the current local preview;
- zero publication-readiness findings.
The accepted reader manifest
and accepted command-reference manifest
pin these facts to public source commit be935053. The website remains a
reviewed derivative: a future HELP, contract, metadata, or manual change must
repeat the upstream validation and acceptance gates before replacing this
snapshot.