chore: fix plugin distribution drift -- symlink docs, templates, example, and repo metadata

[tesles]

Problem

The Claude Code plugin cache only contains files inside claude-code-plugin/. The repo has comprehensive documentation (docs/), scan configuration templates (templates/), and a practice project (example/), but none of it shipped to end users through the marketplace. Users installing the plugin got 57 agents, 17 commands, and 3 hooks -- but zero documentation, no templates (despite CLAUDE.md referencing them), and no example project.

The cache cannot path-traverse outside the plugin root. Content must exist inside claude-code-plugin/ to be included.

Solution

Symlinks inside claude-code-plugin/ pointing to repo-root content. The plugin cache follows symlinks during the copy process (per official docs), so the real files land in the cache without duplicating them in the repo.

New symlinks (10)

docs/ subdirectories (4):

• docs/guides/ -- 9 operational guides (hooks troubleshooting, debug panel, browser tools, custom skills)
• docs/scanning/ -- 4 scanning reference docs (office, pdf, scan config, custom prompts)
• docs/skills/ -- 17 knowledge domain docs (accessibility rules, framework patterns, severity scoring)
• docs/tools/ -- 5 tool integration guides (axe-core, lighthouse, github scanner, MCP tools, VPAT)

Root-level (6):

• example/ -- deliberately broken test page for end-user practice
• CHANGELOG.md, LICENSE, CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md

Previously created symlinks (7, included in this branch)

• templates/ -- scan config profiles (strict/moderate/minimal for office, pdf, epub)
• docs/advanced/, docs/agents/, docs/architecture.md, docs/configuration.md, docs/getting-started.md, docs/hooks-guide.md

Metadata updates

• plugin.json: 3.0.0 -> 3.1.0, added homepage and repository fields, corrected agent count to 57
• marketplace.json: 1.0.0 -> 1.1.0, aligned description, corrected agent count to 57

Excluded from distribution

• docs/prompts/ -- Copilot platform content (.github/prompts/), not Claude Code
• Internal planning docs (AGENT-ECOSYSTEM-PLAN.md, AGENTIC-BROWSER-TOOLS.md, BROWSER-TOOLS-TESTING.md, HOOKS-CROSS-PLATFORM-STRATEGY.md, RESEARCH-SOURCES.md)
• Separate distribution channels (desktop-extension/, vscode-extension/)
• Internal tooling (cache/, context_portal/, plans/)
• Lifecycle scripts (install.sh/ps1, uninstall.sh/ps1, update.sh/ps1) -- marketplace handles this
• Gemini platform files, sample audit output, dev tooling artifacts

Verification

All 17 symlinks resolve to valid targets. No broken links.

[tesles]

@jeffreybishop The A11y check is flagging the docs/ files as having Markdown violations. Given the fact that the docs already existed on main prior to my PR, should it be classified as a false positive?

[accesswatch]

Clean approach using symlinks for plugin distribution. One question before approval:

Windows symlink compatibility: Git on Windows defaults to core.symlinks=false, which converts symlinks to text files containing the target path. This would break the plugin cache since the files would contain paths, not content. Can you confirm whether:

• The Claude Code plugin cache resolves symlinks during copy (your PR description references this), and if so, does that also work on Windows?
• Or should we add a note that Windows users need core.symlinks=true in their git config?
• Alternatively, would a build/copy step be more portable than symlinks?

Version bumps and exclusion list look correct. Happy to approve once the Windows question is resolved.

[accesswatch]

@tesles @accesswatch — Jumping in to help resolve the Windows symlink question so we can move this forward.

Windows Symlink Compatibility — Answer

The concern is valid but manageable. Here's how it breaks down:

End users (plugin install via marketplace): Not affected. The Claude Code plugin cache copies files at the filesystem level after checkout. On macOS/Linux (where the vast majority of Claude Code users are), symlinks just work. The official plugin docs confirm the cache follows symlinks during copy.

Windows end users: Also fine if they have core.symlinks=true in their git config (requires Windows Developer Mode or admin elevation at clone time). This is a well-known Git-on-Windows requirement for any repo using symlinks. Without it, git creates text stub files (e.g., a file containing ../CHANGELOG.md instead of a real symlink), and the plugin cache would copy the stubs, not the real content.

Contributors cloning on Windows: Same requirement — need core.symlinks=true.

Recommended Approach

The symlink approach is the right call — it avoids file duplication and keeps content in sync automatically. To address the Windows edge case:

1. Add a .gitattributes entry at repo root to hint at symlink usage:

   # Symlinks in claude-code-plugin/ point to repo-root content
   claude-code-plugin/CHANGELOG.md    symlink
   claude-code-plugin/LICENSE          symlink
   claude-code-plugin/CONTRIBUTING.md  symlink
   claude-code-plugin/SECURITY.md      symlink
   claude-code-plugin/CODE_OF_CONDUCT.md symlink
   claude-code-plugin/docs/**          symlink
   claude-code-plugin/templates        symlink
   claude-code-plugin/example          symlink
   

2. Add a note in the Getting Started or Contributing docs that Windows users should clone with:

   git clone -c core.symlinks=true https://github.com/Community-Access/accessibility-agents.git
   

   Or set it globally: git config --global core.symlinks true (requires Developer Mode).

3. Optionally add a CI check in the existing workflow that verifies all symlinks resolve to valid targets (prevents future breakage if files move).

Before Merge

This PR's base is stale (c2200c0 vs current main 457036589). @tesles — could you rebase onto current main and resolve any conflicts? There have been several merges since March 5 (PRs #59, #62, #70) that may affect the manifest and a few docs.

Once rebased with the .gitattributes addition, I think this is good to approve and merge.

[accesswatch]

Thanks for the thorough symlink work, @tesles! We've rebased your changes onto current main, resolved the merge conflict in plugin.json, and added the Windows symlink support that @accesswatch flagged:

• .gitattributes added - marks all claude-code-plugin/ symlinks so Git knows about them
• CONTRIBUTING.md updated with Windows clone instructions (core.symlinks=true + Developer Mode)

Everything is now merged to main in bd1ebcc. Closing this PR as the changes are fully incorporated.