docs(agents): surface docs/solutions as a searchable knowledge store#27
Merged
Conversation
AGENTS.md mentioned `docs/solutions/` only as a `dev`-only path guarded out of `main` by `guard-main-docs.yml`. An agent reading that learned the path is forbidden on `main` but not that it is a searchable knowledge store of cross-repo solutions worth consulting before researching from scratch. Adds a short Documented Solutions section adjacent to Layout: names the symlink target, frontmatter fields (`module`, `tags`, `problem_type`), and the `qmd query "<topic>" --collection solutions` search command. Matches the pattern already in `agentnative-spec/AGENTS.md` and `agentnative-cli/CLAUDE.md`. Discoverability-only edit; no policy change. The `docs/plans/`, `docs/solutions/`, `docs/brainstorms/`, `docs/reviews/` guard-from-main mention later in the file is unchanged.
…solutions from lint The Layout table's column-2 "no" indicator was an em-dash (`—`) wrapped in `<!-- unslop: off --> / <!-- unslop: on -->` so the prose-scorer would not count the 8 cell em-dashes against the file's density score. Cleaner: use `✗` directly, parallel to the existing `✓` for the "yes" rows. Drop the wrap. The `<!-- unslop: off -->` mechanism is for legitimate-but-flagged content the file's author wants the scorer to skip. The Layout table's em-dashes were always "data, not prose" — the wrap was treating them as if they were prose-flagged-but-OK. The ✓ / ✗ pair is the structurally correct fix: data indicators, no need to silence the scorer. Also exclude `docs/solutions/**` from `.markdownlint-cli2.yaml`. The path is a symlink to `~/dev/solutions-docs` (a separate private repo with its own lint config). Once the symlink was added in this PR, this repo's pre-push markdownlint walked into the foreign content and failed on its line-length rules. The exclusion makes the symlink-walk safe.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
AGENTS.mdmentioneddocs/solutions/only in the engineering-docs-on-dev policy context (theguard-main-docs.ymlblock list). An agent reading the file learned the path is forbidden on
mainbut did NOT learn it is a searchableknowledge store with structure to grep against. Add a
## Documented Solutionssection between the Layout block and## Lint & Formatthat surfaces the path, the search invocation, the frontmatter fields, and the recreate-symlinkrecipe.
Mirrors the same triage done in
agentnative-sitePR #138.The symlink at
docs/solutions/was recreated as part of this work but is gitignored globally(
~/.config/git/ignore), so it does not appear in the diff. Each clone needs the symlink locally.Changelog
Documentation
AGENTS.md: add## Documented Solutionssection namingdocs/solutions/as a searchable knowledge store, theqmd query "<topic>" --collection solutionsinvocation, the canonical frontmatter fields (module,tags,problem_type), and theln -s ~/dev/solutions-docs docs/solutionsrecreate recipe.Type of Change
docs: Documentation updateFiles Modified
Modified:
AGENTS.mdBreaking Changes
Deployment Notes
Checklist