#3725 Docs: dependency trust across push, quality, fmt and the registry — Deno-config resolution, read-only lock, package.json mode, the archive's audit record (merges #3728)

One dependency-trust docs update for the swamp-club manual. It covers everything that shipped in this track, merged on 2026-10-23 (Seth): #3728 is folded in here and closed as a duplicate. The behaviour is all on main. Describe what ships, and check each claim against the merged code.

1. Bare imports resolve through the Deno config (#3612, #3637); originally this issue

swamp-club#3612 changes extension push and quality to resolve bare imports the way Deno does: deno.json or deno.jsonc, importMap file references, scopes and workspace members, read from the deno info module graph. Quality's local scorer stops receiving the import map, matching the registry's scorer.

Stale manual text once 3612 ships:

• content/manual/reference/extensions/publishing.md, around line 128: says quality still prints the rubric, which resolves the import map locally, and that the bare-specifiers finding names each import's target from the import map. Since swamp-club#3637 push rewrites every import the config resolves, so a bare import left as written is one the config does not resolve; after 3612 the local rubric uses no import map, as the registry does. The sample output near line 206 quotes the same claim.
• content/manual/reference/extensions/manifest.md, lines 915 to 928: the bare-specifier row says a bare import requires a deno.json import map. It should say the project's Deno config (deno.json or deno.jsonc imports, an importMap file, or a scope covering the module), and that push writes the target Deno resolves for that module in the shipped source.
• Check how-to/extensions/improve-score.md line 133 and reference/extensions/scorecard-rubric.md line 85 for consistency (both say no import map at score time, which stays true).

Suggested content: one short paragraph on config discovery (deno.json, then deno.jsonc, walking up from the manifest) and resolution (as Deno resolves it, per importing module); an unresolved bare import ships as written and raises the bare-specifiers warning.

2. extension fmt treats deno.lock as read-only (#3717); from #3728

swamp-club#3717 changes extension fmt and fmt --check, so the fmt section of content/manual/reference/extensions/publishing.md (## fmt, ### Output) is out of date once it ships.

What changed:

• fmt and fmt --check read the module graph with the lock read-only, as push and quality do since #3613. They never create a deno.lock, and never rewrite an existing one.
• On a lock that no longer matches deno.json or package.json, fmt still passes (exit codes unchanged). Each entry point the lock refused is formatted and linted alone, without the local modules it imports. fmt prints a WRN line naming the lock, the project file and the command push asks for: deno install --entrypoint followed by the entry points, run in the project directory.
• In --json, the check and fix objects gain an optional staleLockfiles array; each entry has lockPath, projectFile, projectDir, entryPoints and command. The field is absent when no lock is stale.

Suggested content: one paragraph under ## fmt saying fmt treats the lock as read-only, the WRN line as an example under ### Output, and staleLockfiles in the JSON description. The explanation page extension-trust.md may want one sentence that fmt joins push and quality in never rewriting the lock.

3. package.json mode (#3630, which includes #3632 and #3782)

• In push and quality, bare imports resolved through package.json are audited at the version installed in node_modules. Push ships each one as npm:@.
• Push leaves the author's node_modules/ unchanged.
• A node_modules/ above the repo no longer breaks push when the extension has no deno.json or package.json (#3782). With either file present, Deno itself refuses TypeScript under node_modules.
• Findings for a deprecated or yanked installed version give the fix (a range in package.json says to run npm install afterwards).

4. The archive records audited versions (#3662)

• Push writes extension/dependency-audit.json into the archive: {"recordVersion":1,"dependencies":[{registry, name, spec, version, from}]}, always present, with an empty list when there's nothing to audit.
• spec is what the shipped source writes after @, or null. package.json-mode imports use the installed version as spec.
• The package cache hash now covers deno.lock, so changing only the lock rebuilds the bundle.
• installed is a new resolvedFrom value.

5. The registry audits the recorded version (#3778)

• The registry scorecard audits the version the archive records (OSV, deprecation, JSR yank, license), not its newest match for a range.
• The loose-specifier finding still applies to the spec as written.
• The registry checks each record entry against what it publishes and ignores entries it can't trust (outside the range, non-semver, unpublished, unknown registry). Archives without a record keep the old behaviour.
• The scorecard text says which version was audited and why.

Pages to check

• reference/extensions/publishing.md (push, quality, fmt sections and sample output)
• reference/extensions/manifest.md (bare-specifier row)
• reference/extensions/scorecard-rubric.md, how-to/extensions/improve-score.md
• explanation/extension-trust.md (or wherever dependency trust is explained)

Out of scope

The swamp repo's own skill references (.claude/skills/swamp/references/extension). If those are stale too, that's a separate swamp issue.

Acceptance

• Every statement matches main, with examples taken from real command output.
• The manual's own checks and build pass.