references are an alternative to skills — markdown docs the agent loads on demand. inspired by vercel's finding that an always-loaded AGENTS.md index outperformed SKILL.md-style discovery on their evals.

$ rosie install vercel/next.js --ref
# installs the repo's README.md as a reference

$ rosie install anthropics/skills --ref --skill pdf
# installs a specific SKILL.md (frontmatter stripped)

$ rosie install owner/repo --ref --name custom-name
# override the default install name

the doc lands at .agents/references/<name>/REFERENCE.md, and an entry is appended to a rosie-managed block in the project's agent-instructions file:

<!-- AGENTS.md (or CLAUDE.md, whichever the project already uses) -->

<!-- rosie:references:start -->
<references>
- [Next.js — The React Framework](./.agents/references/vercel-next.js/REFERENCE.md)
- [PDF Processing Guide](./.agents/references/anthropics-skills-pdf/REFERENCE.md)
</references>
<!-- rosie:references:end -->

• ▸ target file AGENTS.md · else CLAUDE.md · else GEMINI.md · else .github/copilot-instructions.md · else creates AGENTS.md
• ▸ title re-extracted from the first H1 of each REFERENCE.md on every rebuild · falls back to install name
• ▸ default name owner-repo · or owner-repo-skill with --skill · override with --name
• ▸ same lockfile recorded with kind ref · same pin/auto semantics as skills · same rosie update
• ▸ project-scoped no symlinks into agent dirs · --global is rejected (the index file is per-project)

npm packages with --npm — symlink .md files straight from node_modules/<pkg>/. tracks the installed version (read from package.json); rosie update re-walks and reconciles after npm update.

$ rosie install react --ref --npm
# symlinks README.md + docs/**/*.md → .agents/references/react-*

$ rosie install @tanstack/react-query --ref --npm

$ rosie install zod --ref --npm --include README.md
# --include replaces the default scope (repeatable)