# Path Resolution Migration Plan

> This plan describes the concrete work needed to migrate README generation to the final path-resolution strategy (relative asset paths resolved per output file).

- Skill: `tools-only/path-resolution-migration-plan` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/path-resolution-migration-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/path-resolution-migration-plan/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/path-resolution-migration-plan

---

# Path Resolution Migration Plan

This plan describes the concrete work needed to migrate README generation to the
final path-resolution strategy (relative asset paths resolved per output file).

## Scope

- Keep style-specific templates intact (extra/classic/awesome/flat).
- Remove all path-specific assumptions from templates and markup.
- Centralize asset path resolution in the generator.

## Plan

1. **Audit templates and markup**
   - Inventory all occurrences of `{{ASSET_PREFIX}}`, `{{ASSET_PATH(...)}}`, `assets/`, `../assets`, `/assets`.
   - Identify every generator/markup call site that injects or assumes a prefix.
   - Map all output locations (root README, README_ALTERNATIVES, .github, etc.).

2. **Introduce a single asset token scheme**
   - Choose one token format (e.g., `asset:foo.png` or `{{ASSET_PATH('foo.png')}}`).
   - Implement a resolver that:
     - finds `repo_root` via `pyproject.toml`
     - computes a relative path from the output file’s directory to `/assets`
     - replaces tokens with correct POSIX paths
   - Remove `ASSET_PREFIX` and `is_root_readme` assumptions from templates.

3. **Wire the resolver into generation**
   - Apply the resolver after template substitution but before writing files.
   - Update markup helpers to emit tokenized asset references instead of prefixes.
   - Ensure style selector and repo ticker resolve through the same mechanism.

4. **Add generated-file header**
   - Insert `<!-- GENERATED FILE: do not edit directly -->` into all outputs.
   - Ensure templates or generator handle this consistently.

5. **Update tests and docs**
   - Add/adjust tests to validate asset paths for all output locations.
   - Ensure `test-regenerate` remains the canonical drift check.
   - Update docs to reflect the new token scheme and remove obsolete guidance.

## Completion Criteria

- No templates or markup contain concrete asset prefixes.
- Outputs render correctly in-place and on GitHub across all locations.
- `make test-regenerate` passes with a clean working tree.