Upstream PR Preparation [Spec]

CLAUDE.md

@@ -3,4 +3,5 @@
 <!-- SPECKIT START -->
 For additional context about technologies to be used, project structure,
 shell commands, and other important information, read the current plan
+at specs/019-upstream-pr/plan.md
 <!-- SPECKIT END -->

brainstorm/00-overview.md

@@ -1,6 +1,6 @@
 # Brainstorm Overview
 
-Last updated: 2026-07-03 (021 brainstormed)
+Last updated: 2026-07-11 (024 brainstormed)
 
 ## Active Sessions
 
@@ -10,8 +10,11 @@ Last updated: 2026-07-03 (021 brainstormed)
 | 015 | 2026-06-30 | local-port-listener | active | - | - |
 | 016 | 2026-07-01 | reverse-forwarding | active | - | [#18](https://github.com/rhuss/openshell-sdk-go/issues/18) |
 | 018 | 2026-07-02 | edge-auth | spec-created | 016 | [#20](https://github.com/rhuss/openshell-sdk-go/issues/20) |
-| 020 | 2026-07-03 | oidc-login | active | - | [#24](https://github.com/rhuss/openshell-sdk-go/issues/24) |
+| 020 | 2026-07-03 | oidc-login | spec-created | 018 | [#24](https://github.com/rhuss/openshell-sdk-go/issues/24) |
 | 021 | 2026-07-03 | sdk-dashboard-tui | active | - | [#25](https://github.com/rhuss/openshell-sdk-go/issues/25) |
+| 022 | 2026-07-03 | auth-guide | active | - | [#28](https://github.com/rhuss/openshell-sdk-go/issues/28) |
+| 023 | 2026-07-03 | schema-docs | active | - | [#29](https://github.com/rhuss/openshell-sdk-go/issues/29) |
+| 024 | 2026-07-11 | upstream-pr | specified | 019 | [NVIDIA/OpenShell#2044](https://github.com/NVIDIA/OpenShell/issues/2044) |
 
 ## Attic (implemented)
 
@@ -87,6 +90,11 @@ Last updated: 2026-07-03 (021 brainstormed)
 - Other edge proxy convenience constructors (Google IAP, Zscaler) when concrete use cases arise (from #018, future brainstorm)
 - Gateway management operations (Add, Remove, SetActive) if Go programs need them (from #019, future brainstorm)
 - Multi-gateway client support (connecting to multiple gateways from one process) (from #019, future brainstorm)
+- Should sdk/go/ have its own CODEOWNERS entry for Go-specific review? (from #024)
+- Should Go SDK CI steps run only when sdk/go/ or proto/ files change (path filter)? (from #024)
+- Does the Fern docs build need Go SDK pages validated separately? (from #024)
+- Should the Go SDK have its own release tagging scheme (e.g., sdk/go/v0.1.0)? (from #024)
+- How should `option go_package` be added to upstream proto files without breaking existing consumers? (from #024)
 
 ## Resolved Threads
 - Interface evolution: follow client-go pattern, accept interface growth, provide fake, use concrete `*Client` in production

brainstorm/022-auth-guide.md

@@ -0,0 +1,76 @@
+# Brainstorm: Authentication Guide
+
+**Date:** 2026-07-03
+**Status:** active
+**Issue:** https://github.com/rhuss/openshell-sdk-go/issues/28
+
+## Problem Framing
+
+The SDK documentation covers individual API endpoints (16 pages under
+`docs/src/api/`) but has no unified entry point for authentication.
+A developer asking "how do I authenticate?" has to piece together
+information from `api/client.md`, `api/gateway.md`, `api/oidc.md`,
+and `api/refresh.md`. The new OIDC login package (PR #26) makes this
+gap more visible: there are now four auth modes, three OIDC grant
+types, and a full token lifecycle (login, persist, read, refresh) that
+no single page explains.
+
+Both new developers (choosing an auth method) and existing users
+(adding OIDC to a working setup) need a guide that covers the full
+picture.
+
+## Approaches Considered
+
+### A: Single Guide Page (chosen)
+
+One `docs/src/authentication.md` page under the "Guides" section with:
+- Decision tree for auth method selection at the top
+- Each auth mode documented with when-to-use and code snippets
+- OIDC grant types (browser, keyboard, device code, client credentials)
+- Full token lifecycle section (login writes to disk, gateway.NewClient
+  reads, RefreshableToken handles refresh, expiry triggers re-auth)
+- Cross-links to API reference pages for detailed options
+
+- Pros: single entry point, complete story in one place, easy to find
+- Cons: could get long if many auth methods are added later
+
+### B: Authentication Section (Multiple Pages)
+
+A new SUMMARY.md section "# Authentication" with sub-pages per method
+and a lifecycle page.
+
+- Pros: clean separation, focused pages
+- Cons: more navigation, harder to see the full picture
+
+### C: Guide + Cheat Sheet
+
+Full guide plus a one-pager with just the decision table and code
+snippets for quick reference.
+
+- Pros: serves both learning and copy-paste use cases
+- Cons: two files to maintain, risk of drift
+
+## Decision
+
+**Option A: Single guide page.** At four auth modes and three OIDC
+grant types, a single page stays manageable. Can be split into B later
+if the auth surface grows significantly (e.g., mTLS, custom providers).
+
+## Key Requirements
+
+- Decision tree at the top mapping scenarios to auth methods
+- All four auth modes covered: none, plaintext, cloudflare_jwt, oidc
+- All three OIDC grant types: browser/keyboard, device code, client credentials
+- Token lifecycle: login to disk, gateway.NewClient reads, RefreshableToken
+  handles refresh, expiry and re-auth
+- Code snippets for each auth path (complete, runnable examples)
+- Cross-links to api/oidc.md, api/gateway.md, api/refresh.md, api/client.md
+- SUMMARY.md entry under "Guides" section
+- Works for both new developers and existing SDK users
+
+## Open Questions
+
+- Should the guide mention mTLS as "coming soon" or omit it entirely
+  until implemented?
+- Should the decision tree be a markdown table or a prose flow
+  (if/then style)?

brainstorm/023-schema-docs.md

@@ -0,0 +1,87 @@
+# Brainstorm: Schema and Data Type Documentation
+
+**Date:** 2026-07-03
+**Status:** active
+**Issue:** https://github.com/rhuss/openshell-sdk-go/issues/29
+
+## Problem Framing
+
+The SDK documentation has 16 API reference pages organized by gRPC
+sub-client (Sandboxes, Exec, Providers, etc.) but no dedicated
+documentation for the data types themselves. Types like `SandboxSpec`,
+`PolicyRule`, `ProviderProfile`, and `NetworkPolicyEndpoint` appear
+inline in endpoint pages without field descriptions, relationships,
+or usage context. The `openshell/v1/types/` package contains ~96 types
+across 20 files, but only ~30 are referenced in docs.
+
+For developers working with the SDK, understanding the data model is
+more important than knowing the CRUD methods. A developer creating a
+sandbox needs to understand `SandboxSpec`, `SandboxTemplate`,
+`SandboxStatus`, and their relationships. Currently they have to read
+Go source code to learn this.
+
+## Approaches Considered
+
+### A: Domain-Concept Schema Pages (chosen)
+
+New `docs/src/schema/` directory with pages grouped by domain concept
+(sandbox, policy, provider, etc.). Each page contains field tables,
+type relationships, and usage examples. All 16 existing API pages get
+inline cross-links from type names to the schema pages.
+
+- Pros: types are documented where developers think about them (by
+  domain, not by Go file), cross-links make the docs navigable,
+  examples show types in context
+- Cons: more pages to maintain, requires updating all 16 API pages
+  for cross-links, manual sync with Go source when types change
+
+### B: Single Types Reference Page
+
+One large `docs/src/schema/types.md` page listing all types with
+anchor links, grouped by domain.
+
+- Pros: single page to search, easy to maintain
+- Cons: very long page (~96 types), poor navigation, doesn't scale
+
+### C: Auto-Generated from Go Source
+
+Generate type docs from Go doc comments using a tool like `gomarkdoc`
+or a custom generator.
+
+- Pros: always in sync with source, zero maintenance
+- Cons: output format is hard to customize, loses the narrative
+  structure (relationships, examples, cross-domain context), requires
+  build tooling
+
+## Decision
+
+**Option A: Domain-concept schema pages with inline cross-links.**
+Manual pages give full control over presentation, relationships, and
+examples. Auto-generation (Option C) can be explored later as a
+complement but not a replacement, since the value is in the curated
+relationships and examples, not just field listings.
+
+## Key Requirements
+
+- New `docs/src/schema/` directory
+- Pages organized by domain concept, not Go package structure
+- Proposed pages: sandbox, policy, network-policy, provider, profile,
+  exec, service, config-settings, auth, health, watch-events
+- Each page includes: field tables with types and descriptions, type
+  relationships (containment, references), usage examples
+- Inline cross-links from all 16 existing API pages (first mention of
+  each type becomes a link to the schema page anchor)
+- New "Schema" section in SUMMARY.md between "API Reference" and "Guides"
+- Types derived from Go source in `openshell/v1/types/`
+- Only SDK types documented (proto types excluded per Constitution I)
+
+## Open Questions
+
+- Should the schema section appear before or after the API Reference
+  section in SUMMARY.md? Before gives types prominence, after follows
+  the natural reading flow (learn the API, then dive into types).
+- Should enum-like constants (e.g., `SandboxPhase` values) be
+  documented on the schema pages or kept on the endpoint pages where
+  they're used?
+- Should there be a schema overview page with a visual domain model
+  diagram showing how the major types relate?

brainstorm/024-upstream-pr.md

@@ -0,0 +1,117 @@
+# Brainstorm: Upstream PR Preparation
+
+**Date:** 2026-07-11
+**Status:** active
+**Upstream Issue:** [NVIDIA/OpenShell#2044](https://github.com/NVIDIA/OpenShell/issues/2044)
+
+## Problem Framing
+
+The Go SDK has matured through 18 spec-driven iterations covering all 55
+RPCs, auth (token refresh, OIDC, edge proxy), gateway config, SSH/TCP
+tunneling, fake client, and comprehensive tests. It currently lives at
+`github.com/rhuss/openshell-sdk-go` as a standalone repo. The goal is to
+contribute it upstream to NVIDIA/OpenShell as a draft PR under `sdk/go/`,
+matching the pattern where the Python SDK already lives in `python/`.
+
+This requires several coordinated changes: module path migration, example
+extraction, documentation integration with the Fern-based docs site, CI
+automation for proto freshness, and scoping development artifacts so they
+don't clutter the upstream repo.
+
+## Approaches Considered
+
+### A: Fork-first migration (chosen)
+
+Prepare everything in the `rhuss/OpenShell` fork, then open a single draft
+PR against `NVIDIA/OpenShell`:
+
+1. Create `github.com/rhuss/openshell-examples`, move `examples/oshell/`
+   TUI there with its own `go.mod`
+2. In the OpenShell fork, create branch `sdk/go-sdk`, add `sdk/go/` with
+   the full SDK (rewritten module path, all sub-clients, auth packages,
+   fake client, tests, committed `.pb.go` files)
+3. Include `specs/` as design documentation with a PR note asking upstream
+   whether to keep or remove them
+4. Write Fern MDX docs under `docs/sdks/go/` and wire into navigation
+5. Add `go:proto` mise task + CI validation step
+6. Open as draft PR referencing issue #2044
+
+- Pros: single coherent PR, reviewers see the full picture, docs and CI
+  show production readiness
+- Cons: large PR, import path rewrite touches every file
+
+### B: Minimal SDK first, docs and CI follow
+
+Two sequential PRs: first the code, then docs and CI after feedback.
+
+- Pros: smaller first PR
+- Cons: incomplete picture, reviewers will ask about missing docs/CI
+
+### C: RFC-first, code later
+
+Open an issue proposing the SDK, wait for approval, then submit code.
+
+- Pros: gets buy-in first
+- Cons: slower, issue #2044 already exists as the proposal, code speaks
+  louder
+
+## Decision
+
+Approach A: fork-first migration as a single draft PR.
+
+The SDK is mature enough to present as a complete package. The draft
+status gives reviewers space without merge pressure. Issue #2044 already
+serves as the RFC, so a separate proposal step would be redundant.
+
+## Key Requirements
+
+### Module path migration
+- Change `github.com/rhuss/openshell-sdk-go` to
+  `github.com/NVIDIA/OpenShell/sdk/go` in go.mod and all import paths
+- Consumer imports become
+  `github.com/NVIDIA/OpenShell/sdk/go/openshell/v1`
+
+### Example extraction
+- Move `examples/oshell/` (4,649 LOC, 12 files) to
+  `github.com/rhuss/openshell-examples` as a separate repo
+- Own `go.mod` referencing the SDK via the new module path
+
+### Documentation (Fern MDX)
+- Write Go SDK docs as Fern MDX pages under `docs/sdks/go/`
+  (getting-started, architecture, error-handling, authentication)
+- Wire into `docs/index.yml` navigation alongside Python SDK docs
+- Remove the local mdbook docs (`docs/`) from the PR
+
+### Proto change detection
+- Add `go:proto` mise task in `tasks/go.toml` that regenerates Go
+  bindings from `proto/` using protoc
+- Add CI step in `branch-checks.yml` that runs the task and diffs,
+  failing if generated files are stale
+- Mirrors the Python SDK pattern (`python:proto` mise task)
+- Commit generated `.pb.go` files so consumers can `go get` without
+  needing protoc
+
+### Spec artifacts
+- Include `specs/` directory in the PR as design documentation
+- PR description mentions spec-driven development methodology and asks
+  upstream whether specs should be retained or removed
+- Exclude `brainstorm/`, `.specify/`, `.claude/`, `CLAUDE.md`, `AGENTS.md`
+
+### PR format
+- Draft PR against `NVIDIA/OpenShell` main branch
+- References issue [#2044](https://github.com/NVIDIA/OpenShell/issues/2044)
+- Full SDK shipped at once (all sub-clients, auth, OIDC, edge, tunnels,
+  fake client, tests)
+- Mentions that the SDK was developed using spec-driven development
+  with the spec-kit toolchain
+
+## Open Questions
+
+- Should `sdk/go/` have its own CODEOWNERS entry for Go-specific review?
+- Should the Go SDK CI steps run only when `sdk/go/` or `proto/` files
+  change (path filter), or on every PR?
+- Does the Fern docs build need Go SDK pages validated separately?
+- Should the Go SDK have its own release tagging scheme (e.g.,
+  `sdk/go/v0.1.0`) or follow the main repo's releases?
+- How should `option go_package` be added to the upstream proto files
+  without breaking existing consumers?