docs: correct README install and action examples, and connector.mdx scopes

[carolinaroncaglia]

Summary

Six documentation corrections found by reading the docs against the code while validating the group active / can_approve change. None is a code change; all of them are places where a reader following the published instructions gets a different result than the docs promise.

What changed and why

README — ## source installed a CLI that cannot show this connector's data. The line was go install github.com/conductorone/baton/cmd/baton@main, the retired standalone module, which pins baton-sdk v0.8.24. This connector builds on baton-sdk v0.24.6 and writes resource-level carriers (WithResourceProfile, WithResourceStatus); a pre-v0.19 reader does not serialise those fields at all, so a correct bundle prints profile: null and a disabled user reports STATUS_ENABLED. Measured against the same bundle with both binaries. Replaced with clone-and-build, because go install cannot be used here at all — baton-sdk's module carries replace directives and go install rejects those. The replacement command was run end to end before documenting it.

README — the docker example could not authenticate. It passed BATON_DOMAIN_URL, BATON_API_KEY and BATON_USERNAME; pkg/config/config.go defines only coupa-client-id, coupa-client-secret and coupa-domain. Verified from the config declaration.

README and connector.mdx — both action arguments lacked their value format. user_id was documented as "The ID of the user", but pkg/connector/actions.go runs strconv.Atoi and then requires a positive integer. The README's own examples passed the literal placeholder "USER_ID", which fails on that check. Both now say it is the numeric id from /api/users, and the examples pass a number. Verified from the validation path.

README — the intro and Data Model described a read-only connector. The only capability prose was "will pull down information about", while the connector declares and implements provisioning on five resource types plus account provisioning. --provisioning appeared only inside the pasted --help output. The intro sentence now follows the same shape as the other connector READMEs, and the flag requirement is stated once.

connector.mdx — the read/write scope list asked for two scopes the connector never requests. core.business_entity.write and core.common.write were listed; ScopesReadWrite in pkg/connector/client/auth.go adds only core.user_group.write and core.user.write. Removed both, so readers stop over-granting. Verified from the scope declaration.

connector.mdx — the page was missing the account-group opt-in note and the conditional accounting scope. core.accounting.read is appended only when account-group sync is enabled, behind a resource-type toggle, and the page presented it as unconditionally required with no mention of the opt-in. The published page already carries both; this brings the source file in line with it, so the next docs sync does not drop them.

Not changed, deliberately

• The brew line is correct as it stands: the conductorone/baton tap's formula is GoReleaser-generated and installs the CLI from ConductorOne/baton-sdk releases. The tap name resembling the retired repo is a coincidence.
• The ghcr.io/conductorone/baton:latest reference is left alone. baton-sdk's .goreleaser.yaml publishes no container image, so that image's provenance — and therefore whether it has the same stale-reader problem — could not be established here. Worth a look by someone who can inspect the image.
• The Capabilities table stays hand-maintained. Adding AUTO-GENERATED markers without a generator wired behind them would advertise a regeneration that never happens.

For the reviewer

The two lines most worth a second look are the go install replacement (a behavioural claim about go install and replace directives, which the commit's command was tested against) and the scope removals (check them against pkg/connector/client/auth.go rather than against the previous list).

[linear-code]

CXP-974

[github-actions]

🟡 Suggestion: The Accounts row still shows no Provision support, but userBuilder implements CreateAccount and CreateAccountCapabilityDetails (pkg/connector/users.go:207, :299), and the README change in this PR now advertises "account creation". Since this PR is aligning docs with code and edits this table, consider adding the provision check to the Accounts row so the two pages agree.

[github-actions]

🟡 Suggestion: go build -o will not create missing parent directories, so on a fresh Go install where $(go env GOPATH)/bin does not yet exist this line fails with "no such file or directory". Adding mkdir -p "$(go env GOPATH)/bin" before the build (or building with go build -o baton ./cmd/baton and letting the reader place it) makes the snippet copy-pasteable.

[github-actions]

Connector PR Review: docs: correct README install and action examples, and connector.mdx scopes

Blocking Issues: 0 | Suggestions: 2 | Threads Resolved: 0
Criteria: Criteria status: loaded .claude/skills/ci-review.md from trusted base 244cf8e6ff68.
Review mode: full
View review run

Review Summary

Documentation-only change (README.md, docs/connector.mdx); the full PR diff was scanned for security and correctness issues and no code, config, or dependency manifests were touched. I verified each factual claim against the checkout: the docker env vars match pkg/config/config.go (coupa-domain/coupa-client-id/coupa-client-secret), the removal of core.business_entity.write and core.common.write matches ScopesReadWrite in pkg/connector/client/auth.go, the core.accounting.read opt-in matches the WillSyncResourceType(AccountGroupResourceTypeID) gate in cmd/baton-coupa/main.go:30 and pkg/connector/client/client.go:81, the user_id numeric requirement matches extractAndValidateUserId in pkg/connector/actions.go, and baton-sdk's go.mod does carry replace directives (so go install of its cmd/baton would indeed be rejected). Two non-blocking documentation-consistency suggestions below.

Security Issues

None found.

Correctness Issues

None found.

Suggestions

• docs/connector.mdx:17 — the Accounts row still shows no Provision support although CreateAccount is implemented (pkg/connector/users.go:207) and the new README text advertises account creation (medium-high confidence).
• README.md:38 — go build -o "$(go env GOPATH)/bin/baton" fails on a fresh Go install where $GOPATH/bin does not exist yet (medium confidence).

Prompt for AI agents

Verify each finding against the current code and only fix it if needed.

## Suggestions

In `docs/connector.mdx`:
- Around line 17: The Capabilities table's "Accounts" row has an empty Provision
  column, but the connector implements account provisioning: `userBuilder.CreateAccount`
  and `userBuilder.CreateAccountCapabilityDetails` exist in `pkg/connector/users.go`
  (lines 207 and 299), and the README text added in this PR states that the connector
  "supports provisioning of ... Coupa user accounts". Add the provision check icon to
  the Accounts row so it reads
  `| Accounts | <Icon icon="square-check" iconType="solid"  color="#c937ae"/> | <Icon icon="square-check" iconType="solid"  color="#c937ae"/> |`,
  matching the other provisionable rows.

In `README.md`:
- Around line 38: The build command `go build -o "$(go env GOPATH)/bin/baton" ./cmd/baton`
  writes into a directory that `go build` will not create. On a machine where
  `$(go env GOPATH)/bin` does not exist yet, the copy-pasted snippet fails with
  "no such file or directory". Either prepend `mkdir -p "$(go env GOPATH)/bin"` to the
  snippet, or build into the checkout with `go build -o baton ./cmd/baton` and tell the
  reader to move the binary onto their PATH.

[github-actions]

No blocking issues found.

[mateoHernandez123]

Docs-only, verified against the connector at HEAD: the corrected docker env vars match config_schema.json, the enable_user/disable_user examples and the numeric user_id format match actions.go (extractAndValidateUserId), and the connector.mdx scope edits (dropping core.business_entity.write / core.common.write, making core.accounting.read opt-in) match auth.go. MDX compiles. LGTM.