docs: restructure READMEs so the happy path leads and advanced usage is findable

[dnegstad]

Restructures the three READMEs so the happy path leads and advanced usage is findable, then fixes factual errors found in review.

Main README

Reordered so usage leads: Getting Started → How It Works → Configuration reference → workflows → Troubleshooting → reference → Development → Provenance. Release provenance and Repository Layout were sitting at positions 3 and 4, ahead of any configuration docs.

Added:

• A Contents list; the file has 25+ sections with no navigation outside GitHub's outline sidebar.
• "Verify it worked" — the store/trust checks plus a curl call, so the happy path ends in confirmation rather than an assumption.
• Troubleshooting: output channel names for both extensions, plus the common failure modes (nothing happened, browser still warns, curl fails, Kestrel picks the wrong cert, container push rejected).
• A Commands reference. All three commands were previously mentioned only inside settings-table cells, and the host-side browser trust command not at all.
• A Linux browser trust section. NSS/certutil was documented only in the host extension README, though without it forwarded ports still warn in the browser on Linux hosts.
• The per-entry field table for userCertificates. The host settings table pointed at a "per-entry schema" that did not exist, leaving trustInContainer used in an example but never defined.
• An environment variable reference covering SSL_CERT_DIR, the DEVCONTAINER_DEV_CERTS_* vars, and the DOTNET_GENERATE_ASPNET_CERTIFICATE suppression, with the suppression rationale moved out of How It Works.

Fixed: disambiguated generateDotNetCert, which exists as both a feature option and a host setting and had near-identical descriptions in adjacent tables; repaired a broken sentence in the opening paragraph; normalized "Dev Container" capitalization in prose; linked Prerequisites to Supported Platforms.

Extension READMEs

• Host: added a Commands table; promoted browser trust from a fourth-level subsection to a top-level section next to Quick Start; added a Troubleshooting pointer with the output channel name.
• Remote: dropped a duplicated install-prompt sentence; added "Verify it worked" and a Troubleshooting pointer.
• Both: trimmed the repeated 7-row feature options table to the options that affect that extension, linking to the main reference for the rest; replaced the duplicated dotnet suppression prose with a summary plus link; added a link back to the repository, which neither marketplace page had.

Not included: non-VS Code / setup-cert.sh

An earlier commit documented setup-cert.sh as a manual fallback for JetBrains and other editors. That was removed: install.sh never copies the script into the container, so it isn't reachable in a usable form today and documenting it would promise support that doesn't exist. The Limitations section now states plainly that VS Code is the only supported editor.

Review fixes

• Corrected the env var propagation claim — docker exec -it … bash is covered by the system-bashrc bridge, but docker exec … env and directly exec'd binaries are not.
• SSL_CERT_DIR is only colon-joined when a system CA directory survives pruning; the table implied an unconditional trailing colon.
• Two troubleshooting steps told users echo $SSL_CERT_DIR should start with a literal ~. $HOME expands when profile.d is sourced, so the check failed on healthy installs.
• Rebuilt Repository Layout against the actual tree: it referenced util/paths.ts (lives in shared/) and test/hydrate.mjs (is test/sample-project/hydrate-sample-project.mjs), and omitted the shared/ package entirely. All 41 entries are now verified to exist.

Verification

Docs-only — no source changes. Every setting, default, command ID, output channel name, and environment variable in the new docs was checked against package.json, devcontainer-feature.json, and install.sh. A link checker over all four READMEs reports every internal anchor and relative path resolving, and a path checker confirms all 41 Repository Layout entries exist.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KjJpJFDYwZTq7oYF7zLAkH

[Copilot]

Pull request overview

Restructures documentation around setup, configuration, verification, and troubleshooting.

Changes:

• Reorders the main README and adds navigation and references.
• Expands verification, Linux browser trust, and troubleshooting guidance.
• Aligns extension READMEs with the central documentation.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
README.md	Reorganizes and expands project documentation.
src/vscode-ui-extension/README.md	Updates host extension usage and reference material.
src/vscode-workspace-extension/README.md	Updates remote extension verification and troubleshooting.

Comments suppressed due to low confidence (3)

README.md:212

• This value is not always formed with a colon. When pruning removes every system CA directory, install.sh deliberately emits the trust directory alone to avoid a trailing empty path element (install.sh:280-289,333-339). Document the conditional join so users do not infer that a trailing colon is expected.

| `SSL_CERT_DIR` | `$HOME/.aspnet/dev-certs/trust:` + the resolved `sslCertDirs` | Always |

README.md:401

• echo $SSL_CERT_DIR prints an expanded absolute home path (for example, /home/vscode/.aspnet/...), never a path beginning with the literal ~. As written, a correctly installed feature fails this troubleshooting criterion.

4. **Did the feature actually install?** Check `echo $SSL_CERT_DIR` in a container terminal — it should start with `~/.aspnet/dev-certs/trust`. If it's empty, the feature didn't run; rebuild the container.

README.md:506

• This repository-layout entry references a nonexistent test/hydrate.mjs. The actual hydration script used by the package command is test/sample-project/hydrate-sample-project.mjs, so the current path sends contributors to the wrong location.

  hydrate.mjs                      Assembles a runnable test project from the template + feature

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (4)

README.md:108

• This section describes the browser-trust command as mandatory, but host provisioning already calls trustInNssBrowsers() through LinuxStore.trustCertificate(). Document the command as the retry path after the automatic import fails so users do not repeat a successful trust operation.

On Linux, Firefox and Chromium use [NSS](https://firefox-source-docs.mozilla.org/security/nss/) for certificate trust and do **not** read OpenSSL trust directories or the .NET root store. Without this step, forwarded ports still show a certificate warning in the browser even though `curl` works fine.

Run **Dev Certs: Trust Certificate in Browsers** from the Command Palette on the host. It:

README.md:410

• Windows cannot follow this troubleshooting step: WindowsStore.trustCertificate() deliberately uses certutil.exe, which skips the CryptoAPI confirmation dialog. Split the guidance so Windows users check the host log for import errors instead of looking for a dialog that never appears.

- **Windows / macOS:** confirm you accepted the OS trust dialog on first use. If you dismissed it, the cert exists but isn't trusted — reload the window to re-trigger the flow.

src/vscode-ui-extension/README.md:200

• The Windows implementation uses certutil.exe specifically to avoid the CryptoAPI confirmation dialog, so the parenthetical is factually incorrect. Document the non-interactive trust mechanism instead.

| Windows | Added to `CurrentUser\Root` (triggers system dialog on first use) |

README.md:449

• Browser trust is a separate NSS trust surface on Linux, but it is not always a separate user step because provisioning already attempts the NSS import automatically. Qualify this limitation so it only directs users to manual action when the automatic attempt cannot complete.

- **Linux browser trust is a separate step.** Firefox and Chromium on Linux don't read the OS/OpenSSL trust stores; see "[Linux hosts: browser trust](#linux-hosts-browser-trust)".

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (2)

README.md:141

• This conflates generated and user-managed key support. The production generation path calls generateCertificate(now, expiry) with its RSA-2048 default; ECDSA/Ed25519 keys are accepted when loading user-managed certificates, not generated by the extension. Split those capabilities so users are not promised configurable non-RSA generation.

2. **Host Extension** (`extensionKind: ["ui"]`) runs on your local machine. It generates certificates identical to `dotnet dev-certs https` (same OID marker, same SAN entries, same key parameters) using Node's built-in `crypto` plus `@peculiar/x509` and `pkijs` for X.509 / PKCS#12 — supporting RSA, ECDSA, and Ed25519 keys. On first use, it generates a cert and trusts it in the host OS certificate store. It then serves the certificate material to the remote side via VS Code's cross-host command routing.

README.md:279

• Setting trustInContainer to false does not remove trust artifacts from an earlier installation. installUserCert skips this block when false but only removes the my/ PFX; the existing root-store PFX and named PEM remain trusted. Qualify the claim or add cleanup for those two paths.

| `trustInContainer` | optional, default `true` | Plant the cert in the container's OpenSSL trust directory and .NET root store, so tools inside the container trust the issuer. Setting it to `false` suppresses both of those writes — it does **not** mean "copy the files without trusting them". With trust off, the cert reaches the container only via the .NET `my/` store (when `installUserCertsToDotNetStore` applies to the entry) or [`extraCertDestinations`](#extra-destinations); with neither of those configured, nothing is written for that entry at all. |