microsoft / microsoft/hve-core

docs(reference): decide how generated asset-doc Source fields express artifact paths

Open
#2,631 0 comments 1 reaction 0 assignees View on GitHub
documentation tooling
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.