docs: document auto OAuth fallback for private registries in krknctl

[Nachiket-Roy]

Documentation Update

Changes:

• Updates the Private Registry usage documentation under the krknctl command reference.
• Adds an example demonstrating the new Automatic OAuth2 Fallback mechanism (where users can pass basic auth credentials and let krknctl perform the token exchange automatically).
• Preserves the manual token exchange method as a fallback options alternative.

Reference PR : krkn-chaos/krknctl#139

[netlify]

✅ Deploy Preview for krkn-chaos ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	bd7db73
🔍 Latest deploy log	https://app.netlify.com/projects/krkn-chaos/deploys/6a177d3297fed10008f31861
😎 Deploy Preview	https://deploy-preview-509--krkn-chaos.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[qodo-code-review]

Review Summary by Qodo

(Agentic_describe updated until commit 23bcb03)

Document automatic OAuth2 fallback for krknctl private registries

📝 Documentation

Walkthroughs

Description

• Documents automatic OAuth2 fallback mechanism for private registries
• Adds Option A showing automatic token exchange with credentials
• Preserves Option B for manual token exchange as alternative
• Documents new environment variables for username and password

Diagram

flowchart LR
  A["User provides credentials"] --> B["Option A: Auto OAuth2"]
  A --> C["Option B: Manual Token"]
  B --> D["krknctl handles token exchange"]
  C --> E["User fetches token with cURL"]
  D --> F["Registry authentication"]
  E --> F

Loading

File Changes

1. content/en/docs/krknctl/usage.md 📝 Documentation +26/-8

Add automatic OAuth2 fallback documentation

• Restructured private registry authentication documentation into two options
• Added Option A demonstrating automatic OAuth2 fallback with username/password
• Renamed previous method to Option B for manual token exchange
• Added KRKNCTL_PRIVATE_REGISTRY_USERNAME and KRKNCTL_PRIVATE_REGISTRY_PASSWORD environment
 variables
• Improved code formatting and clarified Podman SDK limitations

content/en/docs/krknctl/usage.md

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (4) 📘 Rule violations (0)

Context used

✅ Compliance rules (platform): 24 rules

1. Podman support contradicts 🐞 Bug ≡ Correctness

Description

The new “Automatic OAuth2 Fallback (Recommended)” section states krknctl will perform an OAuth2
Bearer token exchange, but the same page still says Podman does not support token authentication,
and the prior Docker-only disclaimer for the example was removed. This can mislead Podman users into
following the recommended path and hitting authentication failures.

Code

content/en/docs/krknctl/usage.md[R305-307]

Evidence

The page simultaneously claims automatic OAuth2 Bearer token exchange (Option A) and states that
Podman token authentication is not supported, which are in direct conflict without additional
runtime-specific caveats.

content/en/docs/krknctl/usage.md[289-296]
content/en/docs/krknctl/usage.md[305-337]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The new Option A describes automatic OAuth2 bearer-token exchange as the recommended approach, but the same page still documents that Podman does not support token authentication. This creates contradictory guidance and can cause users (especially Podman users) to follow steps that won’t work.

### Issue Context
The page already contains a platform limitation note for Podman, but the example-specific Docker-only note was removed.

### Fix Focus Areas
- content/en/docs/krknctl/usage.md[289-337]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Stale search index 🐞 Bug ≡ Correctness ⭐ New

Description

The PR updates the private-registry docs (adds new Option A/Option B text), but the tracked
pre-built search index still contains the old version of this section, so search can surface
outdated guidance. This happens because the index is served from static/search-index.json, which
is generated separately and wasn’t updated alongside the content change.

Code

content/en/docs/krknctl/usage.md[R309-310]

Evidence

The docs page now contains the new Option A/Option B section, but the pre-built index still embeds
the older paragraph for that same section. The codebase documents and consumes /search-index.json
as a pre-built artifact generated by scripts/build-search-index.js, so leaving it stale causes
search/index consumers to show outdated content.

content/en/docs/krknctl/usage.md[299-341]
static/search-index.json[623-623]
CLAUDE.md[64-69]
scripts/build-search-index.js[156-175]
api/services/DocumentationIndex.js[30-35]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The documentation page was updated, but the pre-built search index (`static/search-index.json`) is still showing the previous content for this page. This makes search results (and any consumers of `/search-index.json`) inconsistent with the updated docs.

## Issue Context
This repo serves a pre-built index from `/search-index.json` (generated into `static/search-index.json`). When docs change, the index must be rebuilt to match.

## Fix Focus Areas
- content/en/docs/krknctl/usage.md[309-341]
- scripts/build-search-index.js[156-175]
- static/search-index.json[1-999999]

## Suggested fix
1. Run the index build script (per package scripts): `npm run _build:index`.
2. Commit the regenerated `static/search-index.json` so it reflects the new Option A/Option B content.
3. (Optional) If you don’t want this file tracked, remove it from git and ensure all dev/build entrypoints that need search run `_build:index` before serving/building.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Password passed via CLI 🐞 Bug ⛨ Security

Description

Option A’s recommended example instructs users to pass the registry password via
--private-registry-password, which is commonly exposed via shell history and process listings on
shared machines. The docs should explicitly steer users toward env vars (already documented) or the
manual token option when secrets exposure is a concern.

Code

content/en/docs/krknctl/usage.md[R309-314]

Evidence

The Option A example includes --private-registry-password <password> on the command line, while
the same page also lists environment variables that could be used instead (including PASSWORD).

content/en/docs/krknctl/usage.md[305-315]
content/en/docs/krknctl/usage.md[341-347]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The docs recommend passing a password as a CLI flag in Option A. CLI flags are often recorded in shell history and may be visible to other local users via process inspection.

### Issue Context
This page already documents environment variables for private registry configuration and provides Option B (manual token exchange), but Option A should include an explicit warning and/or a safer example using env vars.

### Fix Focus Areas
- content/en/docs/krknctl/usage.md[305-348]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. Missing trailing newline 🐞 Bug ⚙ Maintainability

Description

content/en/docs/krknctl/usage.md ends without a final newline, which can cause noisy diffs and
some tooling/linters to fail.

Code

content/en/docs/krknctl/usage.md[348]

Evidence

The last line of the file is the closing alert shortcode and the PR diff indicates there is no
newline at EOF.

content/en/docs/krknctl/usage.md[341-348]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The markdown file is missing a trailing newline at EOF.

### Issue Context
Git reports `\ No newline at end of file` for this file in the PR diff.

### Fix Focus Areas
- content/en/docs/krknctl/usage.md[348-348]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Previous review results

Review updated until commit 23bcb03

Results up to commit cc5747d

🐞 Bugs (3) 📘 Rule violations (0) 📎 Requirement gaps (0)

1. Podman support contradicts 🐞 Bug ≡ Correctness

Description

The new “Automatic OAuth2 Fallback (Recommended)” section states krknctl will perform an OAuth2
Bearer token exchange, but the same page still says Podman does not support token authentication,
and the prior Docker-only disclaimer for the example was removed. This can mislead Podman users into
following the recommended path and hitting authentication failures.

Code

content/en/docs/krknctl/usage.md[R305-307]

Evidence

The page simultaneously claims automatic OAuth2 Bearer token exchange (Option A) and states that
Podman token authentication is not supported, which are in direct conflict without additional
runtime-specific caveats.

content/en/docs/krknctl/usage.md[289-296]
content/en/docs/krknctl/usage.md[305-337]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The new Option A describes automatic OAuth2 bearer-token exchange as the recommended approach, but the same page still documents that Podman does not support token authentication. This creates contradictory guidance and can cause users (especially Podman users) to follow steps that won’t work.

### Issue Context
The page already contains a platform limitation note for Podman, but the example-specific Docker-only note was removed.

### Fix Focus Areas
- content/en/docs/krknctl/usage.md[289-337]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Password passed via CLI 🐞 Bug ⛨ Security

Description

Option A’s recommended example instructs users to pass the registry password via
--private-registry-password, which is commonly exposed via shell history and process listings on
shared machines. The docs should explicitly steer users toward env vars (already documented) or the
manual token option when secrets exposure is a concern.

Code

content/en/docs/krknctl/usage.md[R309-314]

Evidence

The Option A example includes --private-registry-password <password> on the command line, while
the same page also lists environment variables that could be used instead (including PASSWORD).

content/en/docs/krknctl/usage.md[305-315]
content/en/docs/krknctl/usage.md[341-347]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The docs recommend passing a password as a CLI flag in Option A. CLI flags are often recorded in shell history and may be visible to other local users via process inspection.

### Issue Context
This page already documents environment variables for private registry configuration and provides Option B (manual token exchange), but Option A should include an explicit warning and/or a safer example using env vars.

### Fix Focus Areas
- content/en/docs/krknctl/usage.md[305-348]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Missing trailing newline 🐞 Bug ⚙ Maintainability

Description

content/en/docs/krknctl/usage.md ends without a final newline, which can cause noisy diffs and
some tooling/linters to fail.

Code

content/en/docs/krknctl/usage.md[348]

Evidence

The last line of the file is the closing alert shortcode and the PR diff indicates there is no
newline at EOF.

content/en/docs/krknctl/usage.md[341-348]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The markdown file is missing a trailing newline at EOF.

### Issue Context
Git reports `\ No newline at end of file` for this file in the PR diff.

### Fix Focus Areas
- content/en/docs/krknctl/usage.md[348-348]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-code-review]

Code review by qodo was updated up to the latest commit 23bcb03