microsoft / microsoft/hve-core
docs(reference): decide how generated asset-doc Source fields express artifact paths
- Dominant language
- Python
- Stars
- 1.5k
- Forks
- 301
- Avg merge
- 3d 3h
- Merged PRs (30d)
- 92
Description
## Summary
Generated reference pages under `docs/reference/` render a `Source` field inside their `` block that points at a workspace-root `.github/` path. Raised during review of #2611 as a path-portability concern.
Example from `docs/reference/instructions/experimental/mural/mural-seeding-patterns.md`:
| Field | Value |
|--------|---------------------------------------------------------------------------|
| Source | `.github/instructions/experimental/mural/mural-seeding-patterns.instructions.md` |
## Why this is not covered by the existing portability work
#2607 tracks workspace-root `.github/` paths in distributed AI artifacts, where a hardcoded path breaks because the artifact loads from an extension directory, peer clone, or CLI plugin directory. That issue explicitly excludes this surface:
> `docs/reference/**` is not affected. Asset docs build from frontmatter and metadata, not body text.
That exclusion is accurate for the mechanism #2607 addresses. These pages are published to a documentation site rather than loaded by an agent at runtime, so nothing resolves the path and nothing breaks.
## The open question
The `Source` field is provenance. It answers "which repository file generated this page," and a repository-relative path arguably answers that question correctly for a contributor who wants to edit the source.
The concern worth settling is consistency. The repository is standardizing on portable artifact references, so a reader encountering `.github/` paths in generated documentation cannot easily tell whether that is deliberate provenance or an oversight of the same class as #2607.
## Options
1. Keep the current behavior and document the rationale, so the distinction between provenance metadata and runtime references is explicit and reviewable.
2. Render the `Source` value in a form that signals provenance rather than a loadable path.
3. Leave the value unchanged but exclude the field from any portability lint added by #2607, so the two conventions do not appear to conflict.
Option 1 is the smallest change and preserves the field's usefulness for contributors.
## Scope
Owner is the asset docs generator, `scripts/docs/Generate-AssetDocs.ps1` and `scripts/docs/Modules/DocsHelpers.psm1`. Any change regenerates through `npm run docs:generate` and affects the generated region only.
## Acceptance criteria
- A decision is recorded for how generated `Source` fields express artifact paths.
- If behavior changes, `npm run docs:generate` produces the new form and `npm run docs:generate:check` is clean.
- Any portability lint introduced by #2607 agrees with the decision rather than contradicting it.
Reference: #2611, #2607
Contributor guide
Research direction
Start with scripts/docs/Generate-AssetDocs.ps1 and scripts/docs/Modules/DocsHelpers.psm1, then review the generated Source field in docs/reference/instructions/experimental/mural/mural-seeding-patterns.md and the related issues #2611 and #2607. Decide and record the provenance convention; if behavior changes, run npm run docs:generate and confirm npm run docs:generate:check is clean and compatible with any portability lint.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- powershell
- Domain
- documentation, tooling
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100