docs(copilot): correct CLI syntax and project paths in openspec

Aaronontheweb · Aaronontheweb · commit a6f4d4bbe850 · 2026-05-20T15:59:56.000Z
Cleanup pass over the openspec change docs that Copilot flagged in
review (items 6, 7, 8, 9):

- proposal.md, design.md, tasks.md: replace the non-existent
  '--type github-copilot' flag with the actual positional CLI syntax,
  'netclaw provider add &lt;name&gt; github-copilot --auth oauth-device'.
  ProviderCommand only parses positional &lt;name&gt; &lt;type&gt; args.

- tasks.md: redirect every 'src/Netclaw.Providers.Tests/...' reference
  to 'src/Netclaw.Daemon.Tests/Providers/GitHubCopilot/...' (the
  Providers.Tests project doesn't exist; the GitHubCopilot tests live
  under Daemon.Tests).

- tasks.md §8: drop the imagined 'netclaw provider probe' subcommand
  (not implemented in ProviderCommand) and replace
  'run-tapes.sh init-wizard ...' with the actual harness entry point
  './scripts/smoke/run-smoke.sh light'. Reword §8.7 to describe what
  the add flow actually does (it exercises the probe path internally).
  Also corrects 'Netclaw.sln' to 'Netclaw.slnx'.

- spec.md: ProviderEntry does not carry a name field — it's the
  dictionary key in the Providers config. Reword the auth-expired
  scenario to clarify that the name surfacing happens at the caller
  layer (probe / chat-completion path), not inside
  CopilotAuthExpiredException.

- design.md: rewrite the 'probe' mitigation paragraph to point at the
  real seam (ProviderDescriptorRegistry.ProbeAsync invoked by the
  TUI/CLI add flow), since there's no standalone probe subcommand.
diff --git a/openspec/changes/add-github-copilot-provider/design.md b/openspec/changes/add-github-copilot-provider/design.md
@@ -162,18 +162,19 @@ what RFC 8628 §3.4 expects.
 
 - **[Akt-sh as reference implementation]** Akt-sh is a working third-party
   app, not an official GitHub integration. Wire protocol details could
-  change without notice. → **Mitigation:** the probe path exercises both
-  token exchange and model listing on every `netclaw provider probe` call,
-  so silent drift surfaces quickly. Failure messages include the offending
-  endpoint URL so debugging is direct.
+  change without notice. → **Mitigation:** the probe path
+  (`ProviderDescriptorRegistry.ProbeAsync`, invoked by the TUI/CLI add
+  flow) exercises both token exchange and model listing on every probe,
+  so silent drift surfaces quickly. Failure messages include the
+  offending endpoint URL so debugging is direct.
 
 ## Migration Plan
 
 No data migration required. New provider; no existing configs reference it.
 Operators who want to switch to Copilot run `netclaw provider add <name>
---type github-copilot`, which triggers the device flow and persists the
-GitHub OAuth token alongside other secrets. Rollback: `netclaw provider
-remove <name>` clears the entry.
+github-copilot --auth oauth-device`, which triggers the device flow and
+persists the GitHub OAuth token alongside other secrets. Rollback:
+`netclaw provider remove <name>` clears the entry.
 
 ## Open Questions
 
diff --git a/openspec/changes/add-github-copilot-provider/proposal.md b/openspec/changes/add-github-copilot-provider/proposal.md
@@ -86,7 +86,7 @@ None.
   persistence.
 - **System skills:** `feeds/skills/.system/files/netclaw-operations/SKILL.md`
   should mention the `github-copilot` provider type and the
-  `netclaw provider add ... --type github-copilot` flow (per the System
+  `netclaw provider add <name> github-copilot --auth oauth-device` flow (per the System
   Skills Sync Rule in CLAUDE.md).
 - **Security & operational impact:** the GitHub OAuth token is stored
   plaintext in the existing secrets store, same posture as other API keys.
diff --git a/openspec/changes/add-github-copilot-provider/specs/netclaw-model-providers/spec.md b/openspec/changes/add-github-copilot-provider/specs/netclaw-model-providers/spec.md
@@ -110,8 +110,12 @@ credential on the operator's behalf.
 - **WHEN** the system attempts to exchange the OAuth token at
   `/copilot_internal/v2/token`
 - **AND** the endpoint returns `401 Unauthorized`
-- **THEN** the system SHALL raise an authentication-expired error
-  identifying the provider entry by name
+- **THEN** the system SHALL raise an authentication-expired error.
+  Higher-level callers (the probe path, the chat-completion path) SHALL
+  include the operator-chosen provider entry name when surfacing the
+  failure to the operator — the name is held by the caller (it is the
+  dictionary key in the `Providers` config), not by the
+  `CopilotAuthExpiredException` itself
 - **AND** the remediation message SHALL direct the operator to remove
   the entry (`netclaw provider remove <name>`) and re-run the device
   flow (`netclaw provider add <name> github-copilot --auth oauth-device`)
diff --git a/openspec/changes/add-github-copilot-provider/tasks.md b/openspec/changes/add-github-copilot-provider/tasks.md
@@ -26,7 +26,7 @@
   any other non-2xx throws an `InvalidOperationException` with the
   endpoint URL and status code in the message
 - [ ] 2.4 Unit tests in
-  `src/Netclaw.Providers.Tests/GitHubCopilot/CopilotTokenExchangerTests.cs`:
+  `src/Netclaw.Daemon.Tests/Providers/GitHubCopilot/CopilotTokenExchangerTests.cs`:
   cache hit (no HTTP), cache miss, 2-minute refresh buffer (FakeTimeProvider),
   401 → `CopilotAuthExpiredException`, non-401 error → `InvalidOperationException`
 
@@ -60,7 +60,7 @@
   `o3-mini`) using `ModelModality.Text` defaults until Copilot exposes
   modality metadata
 - [ ] 4.4 Unit tests in
-  `src/Netclaw.Providers.Tests/GitHubCopilot/GitHubCopilotDescriptorTests.cs`:
+  `src/Netclaw.Daemon.Tests/Providers/GitHubCopilot/GitHubCopilotDescriptorTests.cs`:
   probe success parses + filters, probe falls back on HTTP failure, probe
   surfaces auth-expired clearly on 401 from token exchange
 
@@ -93,21 +93,24 @@
 - [ ] 7.1 Edit
   `feeds/skills/.system/files/netclaw-operations/SKILL.md` — add the
   `github-copilot` provider type to the listing and document the
-  `netclaw provider add ... --type github-copilot` flow
+  `netclaw provider add <name> github-copilot --auth oauth-device` flow
 - [ ] 7.2 Bump `metadata.version` in the skill's YAML frontmatter (do NOT
   run `generate-skill-manifest.sh` locally — CI handles publishing per
   CLAUDE.md)
 
 ## 8. Quality gates and verification
 
-- [ ] 8.1 `dotnet build Netclaw.sln` clean
-- [ ] 8.2 `dotnet test src/Netclaw.Providers.Tests/Netclaw.Providers.Tests.csproj --filter "FullyQualifiedName~GitHubCopilot"` passes
+- [ ] 8.1 `dotnet build Netclaw.slnx` clean
+- [ ] 8.2 `dotnet test src/Netclaw.Daemon.Tests/Netclaw.Daemon.Tests.csproj --filter "FullyQualifiedName~GitHubCopilot"` passes
 - [ ] 8.3 `dotnet test src/Netclaw.Configuration.Tests/Netclaw.Configuration.Tests.csproj --filter "FullyQualifiedName~OAuthDeviceFlow"` passes
 - [ ] 8.4 `dotnet slopwatch analyze` — no new violations
 - [ ] 8.5 `./scripts/Add-FileHeaders.ps1 -Verify` — all new `.cs` files
   carry the Petabridge copyright header
-- [ ] 8.6 `./scripts/smoke/run-tapes.sh init-wizard --no-up --keep-stack` —
+- [ ] 8.6 `./scripts/smoke/run-smoke.sh light` —
   TUI provider picker shows "GitHub Copilot" without breaking existing tapes
 - [ ] 8.7 Manual end-to-end smoke against a real Copilot subscription:
-  `netclaw provider add copilot-personal --type github-copilot`,
-  `netclaw provider probe copilot-personal`, and a one-shot chat
+  `netclaw provider add copilot-personal github-copilot --auth oauth-device`
+  then re-run the same `provider add` command to confirm the cached
+  Copilot API token round-trips, plus a one-shot chat through the new
+  provider entry. (No `netclaw provider probe` subcommand exists today;
+  the add flow exercises the probe path internally.)
