docs(cli): document project secrets in bundled skill

[shrey150]

The bundled skill used by browse skills show and browse skills install omits the secrets commands released in Browse 0.11.0. Document project secret creation, rotation, metadata lookup, cursor pagination, Function attachment, runtime access, and cleanup, including IDs versus names, safe input methods, project enablement, and the local-development limitation.

Includes a browse patch changeset so the updated skill ships with the next CLI release. Website companion: https://github.com/browserbase/browserbase-website/pull/292

Validation:

• Checked all eight secrets command help outputs against installed Browse 0.11.0 and reviewed their implementations.
• Smoke-tested browse skills show using the published 0.11.0 CLI with the updated skill in an isolated temporary package, invoked from a different working directory; stdout matches the complete updated file.
• Both copies' secrets sections match; YAML parsing, Prettier, and git diff --check pass.

E2E Test Matrix

Live production checks on 2026-09-24 used released Browse 0.11.0, SDK Functions 1.0.1, synthetic secrets, and public example.com.

Command / flow	Observed output	Confidence / sufficiency
functions init with npm and pnpm, then publish index.ts --dry-run	Both scaffolded; dry runs succeeded and excluded .env	Fresh scaffold and archive-selection paths
functions publish index.ts from both fresh projects	Both builds COMPLETED, one function each	Single-project credential; portable npm registry URLs required
functions dev index.ts and local invocation	HTTP 200, title Example Domain; shutdown exit 0	Basic local browsing works; context.secrets is absent as documented
cloud secrets create using --env / --stdin; get; paginated list	Exit 0; correct metadata; two distinct one-item pages with time filters	Metadata only; plaintext was not returned
functions secrets attach and paginated list	Both test IDs attached and listed	Real deployed function
functions invoke and invoke --check-status	COMPLETED; returned Example Domain and matching secret hashes/lengths	Includes leading/trailing whitespace preservation
cloud secrets update through env and stdin, then invoke	Updated hashes/lengths matched without redeploy	Rotation reaches deployed runtime
functions secrets detach, then invoke	Detached key absent, other key present	Per-function access removal
cloud secrets delete while attached, then invoke	Deleted key absent	Project-level deletion removes runtime access
Cleanup	Zero test secrets and zero attachments	Synthetic function definitions remain; public API has no function-delete route
Documentation checks	Secrets sections match bundled skill; YAML, added-section Prettier, and diff checks pass	Existing whole-file formatting warnings unchanged

Initial cloud builds failed because the devbox's private npm proxy URLs were embedded in deployment lockfiles. Using public npm URLs fixed those test artifacts; this was not evidence that the secrets commands or ordinary Functions deployment are broken. Private-registry deployments were not validated.

The shared-core work in Stagehand #2701 / sdk-functions-node #40 remains useful for SDK parity and removing duplicated implementation. These successful single-project flows do not establish full parity or local secrets injection.

Context: https://browserbase.slack.com/archives/C0B2H9K1K7T/p1790204127511459

[changeset-bot]

🦋 Changeset detected

Latest commit: a90d689

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
browse	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cubic-dev-ai]

No issues found across 2 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant User
    participant CLI as browse CLI
    participant Skill as SKILL.md (bundled skill)
    participant Browserbase as Browserbase API
    participant Env as Environment Variables
    participant Fn as Deployed Function

    Note over User,Skill: NEW: Project Secrets docs flow

    User->>Skill: Read skill docs
    Skill-->>User: Secrets commands (0.11.0+)

    User->>CLI: browse cloud secrets create KEY --env MY_VAR
    CLI->>Env: Read value from MY_VAR
    Env-->>CLI: Secret value
    CLI->>Browserbase: POST /secrets (encrypted value)
    Browserbase-->>CLI: Metadata {id, secretKey}
    CLI-->>User: Show metadata (not plaintext)

    User->>CLI: browse cloud secrets list --limit 10
    CLI->>Browserbase: GET /secrets?limit=10
    Browserbase-->>CLI: Page {data, nextCursor}
    CLI-->>User: List metadata

    alt nextCursor non-null
        User->>CLI: browse cloud secrets list --cursor <next-cursor>
        CLI->>Browserbase: GET /secrets?cursor=<next-cursor>
        Browserbase-->>CLI: Next page
        CLI-->>User: Next page metadata
    end

    Note over User,Browserbase: Function secret attachment flow

    User->>CLI: browse functions publish
    CLI->>Browserbase: Publish function
    Browserbase-->>CLI: function-id

    User->>CLI: browse functions secrets attach <function-id> <secret-id>
    CLI->>Browserbase: POST /functions/{id}/secrets
    Browserbase-->>CLI: Attachment confirmation

    User->>CLI: browse functions invoke <function-id> --params '{"url":"..."}'
    CLI->>Browserbase: POST /functions/{id}/invoke
    Browserbase->>Fn: Run handler with context
    Fn->>Fn: Read context.secrets.SERVICE_TOKEN
    Fn-->>Browserbase: Result (no secret in output)
    Browserbase-->>CLI: Invocation result
    CLI-->>User: Result

    Note over User,CLI: Cleanup flows

    User->>CLI: browse functions secrets detach <function-id> <secret-id>
    CLI->>Browserbase: DELETE /functions/{id}/secrets/{secret-id}
    Browserbase-->>CLI: Detach confirmation

    User->>CLI: browse cloud secrets delete <secret-id>
    CLI->>Browserbase: DELETE /secrets/{secret-id}
    Browserbase-->>CLI: Delete confirmation

    Note over User,CLI: Local dev limitation
    User->>CLI: browse functions dev
    CLI->>Fn: Run local function
    Fn-->>CLI: context.secrets NOT populated
    CLI-->>User: 0.11.0 limitation

    Note over User,Skill: Input methods
    User->>CLI: browse cloud secrets create KEY (no --env)
    CLI->>User: Hidden terminal prompt
    User->>CLI: Enter secret value
    CLI->>Browserbase: POST /secrets (encrypted)

    alt Automation with --stdin
        User->>CLI: pipe output with --stdin
        CLI->>CLI: Preserve whitespace/trailing newlines
        CLI->>Browserbase: POST /secrets
    end

Loading

_{Re-trigger cubic}