docs(agents): compact root guidance and preserve task-specific knowledge (#1645)

* docs(agents): compact root guidance and preserve task-specific knowledge

* fix(agents): parse guidance navigation with Markdown tokens

* fix(agents): validate generic literal repository paths

* fix(agents): distinguish code symbols and shortcut images

* fix(agents): recognize SCSS filename literals

* fix(agents): handle fenced imports and encoded paths

* fix(agents): parse prose and rendered HTML anchors

* fix(agents): validate rendered HTML navigation

* fix(agents): use GitHub-compatible heading slugs

* fix(agents): require standalone top-level Claude import

* fix(agents): exclude HTML-contained guidance imports

* fix(agents): handle image fragments and quoted imports

* fix(agents): validate visible HTML and image source sets

* fix(agents): recognize package scopes and route source work

* fix(agents): parse JSONC and constrain package exemptions

* fix(agents): decode link entities and allow package subpaths

* fix(agents): route source work and check extensionless files

* fix(agents): support package versions and source fragments

* fix(agents): accept qualified package prose

* fix(agents): retain rendered context for Markdown references

* fix(agents): validate visible headings and spaced paths

* fix(agents): validate media and hyphenated literal paths

* fix(agents): decode full HTML entities and media assets

* fix(agents): recognize possessive package mentions

* fix(agents): validate extensionless imports and version comparators

* fix(agents): retain visible backticks and explicit path punctuation

* fix(agents): validate image-map navigation targets

* fix(agents): count all Markdown line endings in budgets

* fix(agents): delimit package prose at Unicode punctuation

* fix(agents): normalize punctuation for extensionless imports

* fix(agents): preserve filenames across prose punctuation

* fix(agents): validate iframe document references

* fix(agents): inspect document suffix before URL fragments

* fix(agents): unify Markdown suffix and encoded import guards

* fix(agents): handle wildcard versions and alternate documents

* fix(agents): validate document formats and trim HTML URLs

* fix(agents): cover document families and guidance basenames

* fix(agents): require files for media references

* fix(agents): preserve block boundaries and validate embeds

* fix(agents): normalize internal HTML URL whitespace

* fix(agents): reject empty media and ignore URL at-signs

* fix(agents): validate srcdoc references and empty srcset

* fix(agents): honor HTML bases and preserve adjacent imports

* fix(agents): convert base file URLs to native paths

* fix(agents): preserve imports after bare URL punctuation

* fix(agents): exclude opaque URI prose from import scans

* fix(agents): keep import tokens outside URI scheme matches

* fix(agents): restrict opaque URI exemptions to parsed links

* fix(agents): handle opening prose delimiters

* fix(agents): scan nested imports and share document suffixes

* fix(agents): reject pathless media and direct file URLs

* fix(agents): reject file bases and preserve quoted URL boundaries

* fix(agents): distinguish URL quotes and cover guidance variants

* fix(agents): validate SVG images and conventional guides

* fix(agents): handle declared package names handles and SVG use

* fix(agents): normalize closing punctuation on federated handles

* fix(agents): normalize Unicode punctuation on handles

* fix(agents): normalize possessive federated handles

* fix(agents): separate parenthetical prose from handles

* fix(agents): exclude www autolinks from import scanning

* ci: allow manual CodeQL validation of PR branches

* fix(agents): reject nonportable Windows drive links

docs/architecture/validation-map.md

@@ -11,6 +11,16 @@ pnpm nx show projects --withTarget lint
 pnpm nx show projects --withTarget e2e
 ```
 
+## Manual CI Runs
+
+When a PR event does not start checks for the current head, dispatch CI and E2E
+with `gh workflow run ci.yml --ref <branch>` and
+`gh workflow run e2e-tests.yaml --ref <branch>`. CodeQL also supports
+`gh workflow run codeql-analysis.yml --ref <branch>`; this analyzes the selected
+branch commit instead of the PR merge commit. Verify each run's head SHA before
+using its result as evidence. Docker validation can use
+`gh workflow run docker.yml --ref <branch> -f push=false`.
+
 ## Unit And Type Checks
 
 | Area                               | Command                             |
@@ -152,3 +162,31 @@ are gated by:
 ```bash
 IPTVNATOR_TRACE_PLAYER=1 pnpm run serve:backend
 ```
+
+## Test impact and completion
+
+Before finishing a feature, bug fix, data-flow or UI workflow change, identify
+the affected projects and choose unit, integration, E2E, build, lint and manual
+checks. Bug fixes normally include regression coverage that fails before the
+fix. If automation is impractical, explain why and report the strongest manual
+validation. Update fixtures, mocks, routes and E2E flows when behavior changes.
+Prefer extending the closest existing suite to introducing a parallel suite.
+
+Run targeted unit checks first, then affected E2E for workflows, routing,
+persistence, playback, portals, settings or import flows. Electron IPC, SQLite,
+packaged runtime, external players, native files and Electron-only routes require
+Electron E2E where available, otherwise CDP/manual verification using the
+[debugging guide](../development/electron-debugging.md). Prefer atomized E2E
+targets before broad suites. Final reports name tests changed, commands/results,
+and skipped validation with reasons. Docs-only changes need Markdown validation,
+not app unit/E2E. Tooling validation still requires its own focused tests.
+
+## Agent guidance checks
+
+`pnpm run agents:validate` checks root instruction budgets/imports and guidance
+navigation links/anchors. `pnpm run skills:validate` checks skill frontmatter,
+length, paths and release mirrors. Both tooling suites run through
+`pnpm nx test repository-skills`; syntax checks use
+`pnpm nx lint repository-skills`. The CI guidance check runs regardless of the
+Nx affected set. Semantic preservation of moved contracts is a review task;
+link validation alone cannot prove it.