docs: clarify repo flag requirements and stable ID guidance

[pbeckham]

• Change --repo-id, --repo-url, --repository from [optional] to [conditional] in attestation and trail contexts, explaining that all three must be set together to record repository information
• Add attestationRepoNameFlag constant to distinguish the attestation context from the PR-lookup context (repositoryFlag)
• Clarify --repo-id should be a stable VCS provider ID, not the repo name, as names can change on rename
• Extend commitDescription and beginTrailLongDesc to note that repo flags are auto-set in GitHub Actions, GitLab CI, Bitbucket Pipelines, and Azure DevOps, and must be set explicitly in other CI systems
  https://github.com/kosli-dev/server/issues/5357

[claude]

Claude finished @pbeckham's task in 2m 50s —— View job

---

PR Review: Clarify repo flag documentation

• Run static analysis (build, vet, mod tidy)
• Review code changes against previous review feedback
• Check golden files for correctness
• Post review summary

---

Static Analysis

All checks pass: go build, go vet, and go mod tidy — no issues.

Review Summary

The caret markup issue from previous reviews is fixed. The latest commit (9924c02) correctly removed ^ markup from flag description constants in root.go, while keeping ^ in long description strings (attestArtifact.go, attestation.go, beginTrail.go) where the doc generator converts them to backticks. The golden files no longer contain literal ^ characters — this was the primary blocker from the earlier review round.

The attestationRepoNameFlag separation is well done. The original repoNameFlag (used in listArtifacts and logEnvironment for the --repo flag in PR-lookup context) is preserved, while the new attestationRepoNameFlag provides the correct [conditional] description for the --repository flag in attestation/trail contexts. Clean separation with no confusion between the two use cases.

One minor nit remains — posted as an inline comment. The repoURLFlag changed from "Must be a valid URL if provided" to "Must be a valid URL", which drops the qualifier that clarified validation only applies when the flag is set. Since the flag is [conditional], "Must be a valid URL when provided" would be more precise. This was also flagged in earlier reviews.

Trailing whitespace cleanup in attestArtifact.go:51 and beginTrail.go:18 is a nice touch.

What looks good

• Consistent tri-flag guidance ("All three of --repo-id, --repo-url and --repository must be set") across all flag descriptions and long descriptions
• CI defaults link added to repoProviderFlag, which was previously missing
• Long description paragraphs in attestArtifact.go, attestation.go, and beginTrail.go all mention the supported CI systems, giving users clear actionable guidance

[mbevc1]

Looks good, but tests are failing and needs checking