Point neon init doc links at canonical neon.com/docs pages

[philip]

Overview

neon init surfaced documentation hints (the prerequisite and context fields agents follow) using the old /docs/ai/skills/neon-postgres/references/*.md skill files. Those pages were retired and now only redirect, so this points them at the canonical docs directly: getting started, connection methods, Neon Auth, the serverless driver, the CLI, branching, and the JS SDK.

It also renames the map and its emitted field from skillReferences to docReferences. These are documentation links, not the agent skill files installed by the skills CLI, so the old name implied a connection that does not exist. The emitted-field rename is a small change to the agent protocol output.

Verified all eight new URLs resolve (200) and the old ones 308-redirect onto live pages, so this removes a redirect hop.

Split out of #431 so the doc-link update is easy to review on its own.

This pull request and its description were written by Isaac.

[Copilot]

Pull request overview

Updates neon init to use canonical Neon documentation URLs and renames its emitted documentation field.

Changes:

• Replaces retired skill-reference URLs.
• Renames skillReferences to docReferences.
• Updates tests, snapshots, and adds a patch changeset.

Blocking findings:

• .changeset/init-canonical-doc-urls.md — Critical, 1 vote: preserve skillReferences as a compatibility alias or treat this as a breaking protocol change with appropriate versioning.
• packages/cli/src/init/phases/skills.ts — Critical, 2 votes: existing agents may silently lose documentation links when the field is removed.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Summary
packages/cli/src/init/skills.ts	Defines canonical documentation URLs.
packages/cli/src/init/skills.test.ts	Tests documentation URL mappings.
packages/cli/src/init/phases/skills.ts	Emits docReferences.
packages/cli/src/init/phases/neon_auth.ts	Updates the Neon Auth link.
packages/cli/src/init/phases/getting_started.ts	Updates the getting-started link.
packages/cli/src/init/phases/getting_started.test.ts	Updates prerequisite assertions.
packages/cli/src/init/phases/db.ts	Updates the connection-method link.
packages/cli/src/init/phases/db.test.ts	Updates prerequisite assertions.
packages/cli/src/init/__snapshots__/agent_snapshot.test.ts.snap	Refreshes protocol snapshots.
.changeset/init-canonical-doc-urls.md	Documents the CLI patch release.

Suppressed comments (1)

packages/cli/src/init/skills.test.ts:24

• This test only asserts the getting-started URL exactly; for the other seven it checks only the host and .md suffix. The snapshots do not catch wrong values because they are generated from DOC_REFERENCE_URLS itself, so a typo in any other canonical path would pass. Assert the expected key-to-URL mapping exactly for every entry.

		for (const key of expectedKeys) {
			expect(DOC_REFERENCE_URLS).toHaveProperty(key);
			expect(DOC_REFERENCE_URLS[key]).toMatch(/^https:\/\/neon\.com\//);

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.