@vpxa/aikit 0.1.71 → 0.1.73

package/scaffold/definitions/bodies.mjs

@@ -257,6 +257,17 @@ Before every tool call, verify:
 | \`session-handoff\` | Context filling up, session ending, or major milestone |
 | \`lesson-learned\` | After completing work — extract engineering principles |
 | \`docs\` | During \`_docs-sync\` epilogue — living documentation convention, templates, change-to-doc mapping |
+| \`repo-access\` | **IMMEDIATELY** when YOU or any subagent get auth failures from \`web_fetch\`, \`http\`, or git commands (401, 403, 404, SSO redirect, login HTML, "Permission denied"). NEVER declare a repo "inaccessible" without first loading this skill and walking the Strategy Ladder |
+
+## Repo Access — HARD RULE
+
+**If \`web_fetch\` or \`http\` returns 401, 403, 404, SSO redirect, login page HTML, or any auth-like failure for a repository or code URL:**
+1. **STOP** — do NOT declare the repo "inaccessible" or "behind SSO"
+2. **Load the \`repo-access\` skill** and follow its Strategy Ladder
+3. **Walk all 5 steps** before concluding access is impossible
+4. **Include \`repo-access\` in subagent prompts** when delegating tasks that touch the same repo
+
+This applies to YOU (the Orchestrator) when you use \`web_fetch\`/\`http\` directly, not just subagents.
 
 **When dispatching subagents**, include relevant skill names in the prompt so subagents know which skills to load (e.g., "Load the \`react\` and \`typescript\` skills for this task").
 
@@ -394,7 +405,8 @@ When subagents complete, their visual outputs (from \`present\`) are NOT visible
 | \`requirements-clarity\` | When requirements are vague or complex (>2 days) — score 0-100 before committing to a plan |
 | \`c4-architecture\` | When the plan involves architectural changes — generate C4 diagrams |
 | \`adr-skill\` | When the plan involves non-trivial technical decisions — create executable ADRs |
-| \`session-handoff\` | When context window is filling up, planning session ending, or major milestone completed |`,
+| \`session-handoff\` | When context window is filling up, planning session ending, or major milestone completed |
+| \`repo-access\` | When the plan involves accessing private, enterprise, or self-hosted repositories |`,
 
   Implementer: `**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
 

package/scaffold/definitions/plugins.mjs

@@ -133,4 +133,15 @@ export const PLUGINS = {
     source: 'scaffold/general/skills/docs/SKILL.md',
     required: true,
   },
+
+  'repo-access': {
+    description:
+      'Progressive repository access recovery for private and enterprise git repos — strategy ladder from HTTPS to SSH to CLI OAuth to PAT to local clone',
+    source: 'scaffold/general/skills/repo-access/SKILL.md',
+    required: true,
+    sidecars: [
+      'scaffold/general/skills/repo-access/references/platform-matrix.md',
+      'scaffold/general/skills/repo-access/references/error-patterns.md',
+    ],
+  },
 };

package/scaffold/general/agents/Orchestrator.agent.md

@@ -274,6 +274,17 @@ Before every tool call, verify:
 | `session-handoff` | Context filling up, session ending, or major milestone |
 | `lesson-learned` | After completing work — extract engineering principles |
 | `docs` | During `_docs-sync` epilogue — living documentation convention, templates, change-to-doc mapping |
+| `repo-access` | **IMMEDIATELY** when YOU or any subagent get auth failures from `web_fetch`, `http`, or git commands (401, 403, 404, SSO redirect, login HTML, "Permission denied"). NEVER declare a repo "inaccessible" without first loading this skill and walking the Strategy Ladder |
+
+## Repo Access — HARD RULE
+
+**If `web_fetch` or `http` returns 401, 403, 404, SSO redirect, login page HTML, or any auth-like failure for a repository or code URL:**
+1. **STOP** — do NOT declare the repo "inaccessible" or "behind SSO"
+2. **Load the `repo-access` skill** and follow its Strategy Ladder
+3. **Walk all 5 steps** before concluding access is impossible
+4. **Include `repo-access` in subagent prompts** when delegating tasks that touch the same repo
+
+This applies to YOU (the Orchestrator) when you use `web_fetch`/`http` directly, not just subagents.
 
 **When dispatching subagents**, include relevant skill names in the prompt so subagents know which skills to load (e.g., "Load the `react` and `typescript` skills for this task").
 

package/scaffold/general/agents/Planner.agent.md

@@ -105,6 +105,7 @@ When subagents complete, their visual outputs (from `present`) are NOT visible t
 | `c4-architecture` | When the plan involves architectural changes — generate C4 diagrams |
 | `adr-skill` | When the plan involves non-trivial technical decisions — create executable ADRs |
 | `session-handoff` | When context window is filling up, planning session ending, or major milestone completed |
+| `repo-access` | When the plan involves accessing private, enterprise, or self-hosted repositories |
 
 # Code Agent — Shared Base Instructions
 

package/scaffold/general/skills/aikit/SKILL.md

@@ -29,6 +29,12 @@ Local-first AI developer toolkit — 82 MCP tools for search, analysis, context
 - You need code complexity metrics or a git changelog
 - You want to save and reuse code snippets across sessions
 
+## Skills Reference
+
+| Context | Skill | Load when |
+|---------|-------|----------|
+| Repository access recovery | `repo-access` | When encountering git auth failures, accessing private/enterprise repos, or when `web_fetch`/`http` returns auth errors on repository URLs. |
+
 ## Architecture
 
 10-package monorepo published as a single npm package:

package/scaffold/general/skills/c4-architecture/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: c4-architecture
-description: Generate architecture documentation using C4 model diagrams. Supports two output formats: Mermaid (md) for documentation and HTML/SVG for presentations. Use when asked to create architecture diagrams, document system architecture, visualize software structure, create C4 diagrams, or generate context/container/component/deployment diagrams.
+description: "Generate architecture documentation using C4 model diagrams. Supports two output formats: Mermaid (md) for documentation and HTML/SVG for presentations. Use when asked to create architecture diagrams, document system architecture, visualize software structure, create C4 diagrams, or generate context/container/component/deployment diagrams."
 metadata:
   category: cross-cutting
   domain: general

package/scaffold/general/skills/repo-access/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: repo-access
+description: "Progressive repository access recovery for private and enterprise git repositories. Triggered when: (1) git clone/fetch/pull fails with auth errors (401, 403, 404, Permission denied), (2) web_fetch or http tool returns auth failure on repository URLs, (3) user mentions private repo, enterprise repo, or internal repo, (4) user asks to access code from GitHub Enterprise, GitLab Self-Managed, Bitbucket Server, Azure DevOps. Guides through 5-step progressive strategy: anonymous HTTPS, SSH keys, CLI OAuth, PAT, local clone fallback."
+metadata:
+  category: cross-cutting
+  domain: general
+  applicability: on-demand
+  inputs: [git-error, repository-url, platform-context]
+  outputs: [authenticated-access, recovery-instructions]
+  requires: []
+  relatedSkills: [aikit]
+argument-hint: "Repository URL or error message"
+---
+
+# Repository Access Recovery
+
+Progressively recover repository access for private, enterprise, and internal git hosts without leaking credentials.
+
+## When to Activate
+
+### Reactive triggers
+
+- `git clone`, `git fetch`, or `git pull` fails with `401`, `403`, `404`, `Authentication failed`, or `Permission denied (publickey)`.
+- `http` diagnostics against a repo endpoint show auth failure or ambiguous private-repo responses.
+- `web_fetch` returns login page HTML, SSO redirect, "Sign in", "Page not found", or empty/truncated content for a repo URL.
+- Any tool output contains "behind SSO", "SSO required", "SAML", "requires authentication", or similar auth-gate language about a repository.
+- A repository URL works in a browser for the user but fails from agent tools or terminal commands.
+- **You are about to declare a repo "inaccessible" or "unreachable"** — STOP and activate this skill first.
+
+### Proactive triggers
+
+- The user says the repo is private, enterprise, self-managed, internal, or SSO-protected.
+- The repo is hosted on GitHub Enterprise, GitLab Self-Managed, Bitbucket Server/Data Center, Azure DevOps, Gitea, or another custom git host.
+- The environment may need browser sign-in, SSH agent setup, or token-based recovery before any code access can work.
+
+## When NOT to Activate
+
+- Public repositories that already clone or read successfully over HTTPS.
+- Local-only repositories where no remote auth is involved.
+- Problems caused by branch protection, merge conflicts, or rate limiting rather than repository access.
+
+## Step 0: Platform Detection & Capability Gate
+
+Detect platform from the URL, then decide what recovery options are possible in this environment.
+
+| URL pattern | Platform |
+| --- | --- |
+| `github.com`, or any GHE host (e.g. `ghe.*`, `github.*`, custom domain) | GitHub / GitHub Enterprise |
+| `gitlab.com`, `gitlab.<corp-host>` | GitLab / GitLab Self-Managed |
+| `bitbucket.org`, `bitbucket.<corp-host>` | Bitbucket Cloud / Server |
+| `dev.azure.com`, `visualstudio.com`, `/_git/` | Azure DevOps |
+| anything else with git over HTTPS/SSH | Unknown — ask the user which platform before assuming generic Git |
+
+- Capability gate: has terminal, has browser, or conversation-only.
+- If terminal is unavailable, skip directly to PAT guidance or local clone fallback.
+- If browser is unavailable, prefer SSH or pre-created credentials over CLI OAuth.
+- If only the `http` tool is available (no terminal, no CLI): use PAT + authenticated API reads (see "Web-Based Code Access" below). This is the zero-dependency path — no `gh`, `glab`, or `az` installation needed.
+
+For platform-specific details, read `references/platform-matrix.md`.
+
+## Strategy Ladder
+
+### Step 1: Try HTTPS Anonymous Access
+
+- Goal: prove the repo is public or already reachable without extra auth.
+- What to do: normalize the remote to an HTTPS URL and run `git ls-remote https://...`. If it succeeds, use HTTPS and stop. If it fails with auth-like errors, continue instead of assuming the repo is missing.
+- Verify: `git ls-remote <url>`; SUCCESS -> stop, FAIL -> Step 2.
+
+### Step 2: Check Existing SSH Keys
+
+- Goal: reuse working SSH credentials before asking for new secrets.
+- What to do: inspect `~/.ssh/` for key files, run `ssh-add -l`, then test host auth with `ssh -T git@{host}`. If SSH works, switch the remote to the SSH URL and continue with that transport.
+- Verify: `git ls-remote <ssh-url>`; SUCCESS -> stop, FAIL -> Step 3.
+
+### Step 3: Platform CLI OAuth
+
+- Goal: use the platform's interactive login flow with stored credentials.
+- What to do: check whether the matching CLI exists, for example `which gh`, `which glab`, or `which az` (or platform equivalent). If installed, run `{cli} auth login` and let it complete browser or device OAuth, then retry git access.
+- **If the CLI is not installed**: do NOT try `npx` — platform CLIs (`gh`, `glab`, `az`) are native binaries, not npm packages. Skip straight to Step 4 (PAT). For file-read-only tasks, the `http` tool with a PAT header is a zero-dependency alternative to any CLI.
+- Verify: `git ls-remote <url>`; SUCCESS -> stop, FAIL -> Step 4.
+
+### Step 4: Personal Access Token
+
+- Goal: recover access when SSH and CLI OAuth are unavailable or blocked.
+- What to do: ask the user to create a PAT or app password at the platform-specific URL with minimum read scopes only. Have the user provide it through an env var or credential helper, then configure git credentials without embedding the token in the remote URL.
+- Verify: `git ls-remote <url>`; SUCCESS -> stop, FAIL -> Step 5.
+
+### Step 5: Local Clone Fallback
+
+- Goal: unblock work when remote auth cannot be completed from the current environment.
+- What to do: ask the user to clone the repository on their machine using their normal workflow, then provide the local filesystem path. Use the local checkout as the source of truth for code access.
+- Verify: local repo exists and `git rev-parse --show-toplevel` succeeds; SUCCESS -> stop.
+
+## Security Rules (HARD GATE)
+
+- NEVER include a PAT in a git URL; it leaks into shell history, process lists, logs, and config.
+- NEVER repeat a user's token value in chat output, summaries, examples, or when relaying tool output that may contain credentials.
+- Use env vars, credential helpers, or platform login tools for token delivery.
+- Recommend minimum scopes only: read-only repo scopes, not broad write/admin scopes.
+- Prefer ephemeral credentials, OAuth/device flows, or short-lived tokens over long-lived PATs.
+- When guiding PAT creation, recommend the shortest feasible expiry (7–30 days for task-specific work).
+
+## After Access Is Established
+
+- Remind the user to revoke single-use PATs once the task is complete.
+- If credentials were stored via a credential helper, note that they persist until manually removed or the token expires.
+
+## Web-Based Code Access (web_fetch / http)
+
+Agents often use `web_fetch` or `http` to read individual files without a full clone. These requests fail silently on private repos — GitHub returns `404` or login HTML, not an auth error.
+
+### Common URL Patterns That Fail on Private Repos
+
+| URL Pattern | Platform | What Happens |
+|---|---|---|
+| `raw.githubusercontent.com/{owner}/{repo}/{ref}/{path}` | GitHub | `404` — no auth header accepted |
+| `github.com/{owner}/{repo}/blob/{ref}/{path}` | GitHub web view | `200` with login HTML, not code |
+| `api.github.com/repos/{owner}/{repo}/contents/{path}` | GitHub API | `404` (the GitHub 404 trap) |
+| `<ghe-host>/{owner}/{repo}/*` (any GHE URL) | GitHub Enterprise | `200` with SAML SSO redirect page — body contains "Initiating SAML single sign-on" and redirect to `login.microsoftonline.com` or other IdP |
+| `gitlab.com/{owner}/{repo}/-/raw/{ref}/{path}` | GitLab | `401` or login redirect |
+| `dev.azure.com/{org}/{project}/_apis/git/repositories/{repo}/items` | Azure DevOps | `401` or `203` non-authoritative |
+
+### SAML SSO Detection (CRITICAL)
+
+GHE instances with SAML SSO return `200 OK` with an HTML body that is NOT the requested content. **This is the most common false-"inaccessible" scenario.** Detect it by checking `web_fetch` output for ANY of these strings:
+
+- `Initiating SAML single sign-on`
+- `login.microsoftonline.com` (Azure AD / Entra ID)
+- `You are being redirected to your identity provider`
+- `/login?return_to=`
+- `SAMLRequest=`
+- `RelayState=`
+
+If ANY of these appear → the repo exists and is accessible, it just needs authentication. This is NOT "inaccessible" — follow the Strategy Ladder.
+
+### Recovery: Authenticated API Reads
+
+When `web_fetch` fails on a private repo URL, switch to authenticated `http` calls:
+
+1. **Ensure auth is established first** — walk the Strategy Ladder (Steps 1-4) to get working credentials.
+2. **Use the platform API with auth headers**, not raw/web URLs:
+
+| Platform | Authenticated file-read endpoint | Auth header |
+|---|---|---|
+| GitHub / GHE | `http GET https://api.github.com/repos/{owner}/{repo}/contents/{path}?ref={branch}` | `Authorization: token <PAT>` or use `gh api` |
+| GitLab | `http GET https://gitlab.com/api/v4/projects/{id}/repository/files/{path}/raw?ref={branch}` | `PRIVATE-TOKEN: <PAT>` |
+| Azure DevOps | `http GET https://dev.azure.com/{org}/{project}/_apis/git/repositories/{repo}/items?path={path}&api-version=7.0` | `Authorization: Basic <base64(:PAT)>` |
+| Bitbucket | `http GET https://api.bitbucket.org/2.0/repositories/{owner}/{repo}/src/{ref}/{path}` | `Authorization: Bearer <token>` |
+
+3. **Prefer `http` over `web_fetch`** for private repos — `http` sends proper headers and returns machine-readable JSON; `web_fetch` gets HTML login pages.
+4. **For bulk reads**, prefer `git clone --depth 1` over many individual API calls — it's faster and avoids rate limits.
+5. **NEVER embed tokens in URLs** — use auth headers via the `http` tool or `gh api` CLI wrapper.
+
+### Quick Decision: Clone vs API Read
+
+| Situation | Preferred method |
+|---|---|
+| Need 1-3 specific files | Authenticated API via `http` |
+| Need to browse/search the repo | `git clone --depth 1` (shallow) |
+| Need file history or blame | `git clone` |
+| No terminal available | Authenticated API via `http` with PAT |
+| Rate-limited on API | `git clone --depth 1` |
+
+## Tool Routing
+
+| Tool | Use |
+| --- | --- |
+| `git_context` | Check local repo state and confirm a clone or fallback checkout is usable |
+| `http` | Probe platform APIs for auth diagnostics AND read file contents from private repos with auth headers |
+| `web_fetch` | Only for public repos or after confirming access works; unreliable for private repos (returns HTML, not code) |
+| `web_search` | Find current platform-specific auth documentation when the host is unusual or self-managed |
+| Terminal | Run git commands, SSH tests, CLI auth flows, and credential-helper setup |
+
+For detailed error patterns, read `references/error-patterns.md`.
+
+## CRITICAL: The GitHub 404 Trap
+
+GitHub commonly returns `404 Not Found` for private repositories when the caller is unauthenticated or under-authenticated. NEVER conclude that a GitHub repository does not exist from a `404` alone. Treat that response as an authentication signal first, then walk the ladder before declaring the repo missing.

package/scaffold/general/skills/repo-access/references/error-patterns.md

@@ -0,0 +1,116 @@
+# Repo Access Error Patterns
+
+Use this reference to distinguish missing repositories from authentication and policy failures when probing Git hosts.
+
+## HTTP Status Code Matrix
+
+| Platform | No auth (private repo) | Wrong credentials | Rate limited | SSO required |
+|---|---|---|---|---|
+| GitHub REST API | `404` (TRAP!) | `401` -> `403` | `403` + rate limit body | `403` + `X-GitHub-SSO` header |
+| GitHub Web | HTML "Page not found" or login redirect | Login redirect | - | - |
+| GitLab | `401` | `401` | `429` | `401` (PAT mandatory) |
+| Bitbucket | `403` | `403` | `429` | `403` |
+| Azure DevOps | `401` | `401` | - | `401` |
+
+## CRITICAL: The GitHub 404 Trap
+
+GitHub deliberately returns `404`, not `401`, for private repositories accessed without authentication.
+This is by design to avoid leaking whether a repository exists.
+
+- Never conclude a GitHub repository does not exist from an unauthenticated `404`.
+- `GET https://api.github.com/repos/{owner}/{repo}` without auth returns `404` for both "repo truly missing" and "repo exists but is private".
+- The only reliable disambiguation is an authenticated probe.
+- If the same request still returns `404` with valid auth, the repository is truly missing.
+
+Probe order:
+
+1. Try the authenticated API request first.
+2. If it returns `200`, access works.
+3. If it returns `404` without auth context, treat it as ambiguous and recover.
+4. If it returns `404` with known-good auth, treat the repo as missing.
+
+## Git CLI Stderr Patterns
+
+| Error Text Pattern | Platform | Diagnosis | Action |
+|---|---|---|---|
+| `remote: Repository not found.` | GitHub | Auth failure, not proof the repo is missing | Try auth strategies |
+| `git@github.com: Permission denied (publickey).` | GitHub | SSH key not recognized | Check SSH keys, try HTTPS |
+| `remote: HTTP Basic: Access denied.` | GitLab | Auth failure, 2FA likely | Use PAT; password auth is blocked with 2FA |
+| `error: The requested URL returned error: 403` | Bitbucket | Auth failure | Try app password |
+| `TF401019: The Git repository with name or identifier X does not exist` | Azure DevOps | Auth failure or missing repo | Try PAT with Code:Read scope |
+| `fatal: Authentication failed for 'https://...'` | Any (HTTPS) | General auth failure | Escalate through the strategy ladder |
+| `Permission denied (publickey).` | Any (SSH) | SSH key not recognized | Check `~/.ssh/`, run `ssh-add`, try HTTPS |
+| `fatal: Could not read from remote repository.` | Any (SSH) | SSH access denied | Verify the SSH key is added to the platform |
+| `unable to access '...': SSL certificate problem` | Any | Self-signed or enterprise CA issue | Ask about local cert config; skip to local clone if needed |
+
+Treat these stderr strings as direct signals from tool output. Do not reinterpret GitHub's `Repository not found` as a clean existence check.
+
+## web_fetch / http Tool Detection
+
+- `web_fetch` against a private GitHub repo URL often returns HTML with "Page not found" or a login page.
+- GitHub web responses can be `200` with a 404-looking body, so `web_fetch` is unreliable for auth diagnosis.
+- `http` against the platform API gives machine-readable bodies and real status codes, so use it for probes.
+- For `web_fetch` on `github.com`, inspect the body for `Page not found`, `Sign in`, or `/login` links. If present, assume private or auth-gated access and trigger recovery.
+
+Recommended diagnostic probe:
+
+```text
+http GET https://api.github.com/repos/{owner}/{repo}
+-> 404 + no auth header -> might be private
+-> 401 -> explicit auth failure
+-> 200 -> repo is public, access works
+```
+
+## Edge Cases
+
+| Edge Case | Signal | Response |
+|---|---|---|
+| GitHub.com SAML SSO | `403` + `X-GitHub-SSO: required; url=...` | PAT needs SSO authorization for the org |
+| GHE SAML SSO (web_fetch) | `200` + body contains `Initiating SAML single sign-on`, redirect to `login.microsoftonline.com` or other IdP | Repo EXISTS and is auth-gated. NOT inaccessible. Use PAT + `http` with auth headers, or `gh auth login --hostname <host>` |
+| GHE SAML SSO (http) | `302` redirect to `/login?return_to=...` or IdP URL | Same — repo exists, needs auth. Walk the Strategy Ladder |
+| GHE SAML SSO (git CLI) | `fatal: Authentication failed` or credential prompt | `gh auth login --hostname <host>` or PAT via credential helper |
+
+## SAML SSO — Detailed Pattern
+
+GitHub Enterprise instances commonly use SAML SSO via Azure AD (Entra ID), Okta, or other IdPs. When `web_fetch` hits a GHE URL without auth:
+
+1. GHE returns `200 OK` (not 401/403!) with an HTML page
+2. The HTML contains `Initiating SAML single sign-on` and a redirect URL to the IdP
+3. The redirect URL includes `SAMLRequest=`, `RelayState=`, and often `login.microsoftonline.com`
+4. The agent sees HTML content and may conclude the repo is "inaccessible" or "behind SSO"
+
+**Detection strings** (check `web_fetch` output for ANY of these):
+```
+Initiating SAML single sign-on
+login.microsoftonline.com
+You are being redirected to your identity provider
+/login?return_to=
+SAMLRequest=
+RelayState=
+```
+
+**Correct response:** The repo exists. The `web_fetch` path will never work for SSO-protected GHE. Switch to:
+- `gh auth login --hostname <ghe-host>` (if `gh` CLI available)
+- PAT + `http` with `Authorization: token <PAT>` against `<ghe-host>/api/v3/repos/{owner}/{repo}/contents/{path}`
+- Ask user for local clone if no token can be obtained
+| GitLab 2FA enabled | `401` on password auth | PAT is mandatory; 2FA blocks password auth |
+| Expired token | `401` after providing a valid-looking PAT | Generate a new token and check expiry |
+| GitHub rate limit | `403` + body contains `rate limit` | Not an auth failure; wait or authenticate for a higher limit |
+| IP allowlisting | `403` + body mentions IP or org policies | Cannot be fixed programmatically; skip to local clone (Step 5) |
+| Fine-grained PAT scope | `403` + `insufficient scope` | Switch to a classic PAT for org repos |
+| SSH key not in agent | `Permission denied (publickey)` + key file exists | Run `ssh-add ~/.ssh/id_ed25519` |
+| Wrong SSH username | `Permission denied` | Use `git@host`, not `username@host` |
+| Deploy key conflict | `key is already in use` | Use a user SSH key or PAT instead |
+
+## Escalation Decision Rules
+
+- Retry the same step for transient failures such as DNS failure, timeout, or `5xx` responses.
+- Escalate to the next strategy step for `401`, `403`, `404`, `Permission denied`, `Authentication failed`, or `Access denied`.
+- Skip directly to Step 5 (local clone) for IP allowlisting, enterprise SSL certificate issues, or org policy blocks.
+
+Default interpretation order:
+
+1. Prefer API probes over web page fetches.
+2. Treat GitHub `404` as ambiguous until valid auth disproves privacy.
+3. Treat SSH `publickey` errors as key-distribution failures, not repo absence.
+4. Separate rate limits and org policy blocks from authentication failures before escalating.

package/scaffold/general/skills/repo-access/references/platform-matrix.md

@@ -0,0 +1,142 @@
+# Platform Matrix
+
+Use this reference when a repository URL reveals the hosting platform and the skill needs platform-specific authentication or cloning guidance. Prefer platform CLI login flows or OS-backed credential helpers over raw PAT handling.
+
+## Platform Detection
+
+| URL Pattern | Platform | CLI Tool (optional) | Auth Command | No-CLI Alternative |
+|---|---|---|---|---|
+| `github.com` | GitHub | `gh` | `gh auth login` | PAT + `http` with `Authorization: token <PAT>` |
+| Any custom domain (e.g. `ghe.corp.com`, `github.corp.com`) | GitHub Enterprise | `gh` | `gh auth login --hostname <host>` | PAT + `http` against `<host>/api/v3` |
+| `gitlab.com` | GitLab | `glab` | `glab auth login` | PAT + `http` with `PRIVATE-TOKEN` header |
+| Self-hosted GitLab | GitLab Self-Managed | `glab` | `glab auth login --hostname <host>` | PAT + `http` with `PRIVATE-TOKEN` header |
+| `bitbucket.org` | Bitbucket Cloud | None | N/A | App password + `http` with `Authorization: Bearer` |
+| `dev.azure.com` or `*.visualstudio.com` | Azure DevOps | `az` + GCM | `az login` | PAT + `http` with Basic auth |
+| Gitea instances | Gitea | `tea` (optional) | `tea login add` | PAT + `http` with `Authorization: token` |
+| Unknown or custom domain | Ask user which platform | N/A | N/A | Probe `http` or ask before assuming generic Git |
+
+> **Note:** Platform CLIs (`gh`, `glab`, `az`, `tea`) are native binaries, not npm packages. Do NOT use `npx` to install them — it will fail or install unrelated/unofficial packages. When the CLI is unavailable, use the No-CLI Alternative column.
+
+## GitHub / GitHub Enterprise
+
+- CLI: `gh auth login` uses a browser or device code flow and can open the browser automatically.
+- GitHub Enterprise CLI: `gh auth login --hostname <host>`.
+- PAT creation: `https://github.com/settings/tokens` for classic tokens.
+- PAT creation: `https://github.com/settings/personal-access-tokens` for fine-grained tokens.
+- Minimum scopes: `repo` for classic PATs (NOTE: `repo` grants read and write — prefer fine-grained PATs with `Contents: Read` for read-only access).
+- Minimum scopes: `Contents: Read` for fine-grained PATs.
+- SSH: `git@github.com:owner/repo.git`.
+- Credential helper: `gh auth setup-git` configures Git to use the GitHub credential flow.
+- Note: Fine-grained PATs may not cover organization-level access or every repo path; classic PATs are still required for some org repos.
+- SAML SSO: PATs often require explicit org authorization from `https://github.com/settings/tokens` after creation.
+- Enterprise note: PAT URLs and token policy can vary by host; reuse the same auth pattern with the enterprise hostname and instance settings pages.
+- Enterprise detection: GHE instances use fully custom domains (e.g. `ghe.coxautoinc.com`, `github.acme.com`). If unsure, probe `https://<host>/api/v3` — a GitHub Enterprise instance returns a JSON response with `installed_version`. Use `gh auth login --hostname <host>` with any custom GHE domain.
+
+## GitLab / GitLab Self-Managed
+
+- CLI: `glab auth login` uses a browser-backed OAuth flow.
+- Self-managed CLI: `glab auth login --hostname <host>`.
+- PAT creation: `https://gitlab.com/-/user_settings/personal_access_tokens`.
+- Minimum scopes: `read_repository`.
+- SSH: `git@gitlab.com:owner/repo.git`.
+- Credential helper: `glab auth setup-git` configures Git credential handling.
+- Note: If 2FA is enabled, username/password Git auth is blocked; a PAT is mandatory for HTTPS auth.
+- Self-managed note: PAT URL is typically `https://<host>/-/user_settings/personal_access_tokens` unless the instance customizes settings paths.
+
+## Bitbucket Cloud
+
+- CLI: No official first-party CLI OAuth flow for repo auth.
+- PAT/App Password creation: `https://bitbucket.org/{workspace}/settings/app-passwords`.
+- Minimum permissions: `Repositories: Read`.
+- SSH: `git@bitbucket.org:owner/repo.git`.
+- Note: Bitbucket Cloud uses App Passwords rather than standard PAT terminology.
+- Note: HTTPS auth requires both the Bitbucket username and the app password, delivered through a credential helper or `GIT_ASKPASS` script — never embedded in the clone URL.
+
+## Azure DevOps
+
+- CLI: `az login` authenticates to Microsoft Entra ID; Git Credential Manager then handles Git credentials automatically.
+- PAT-based auth remains the fallback when Entra ID or GCM is unavailable.
+- PAT creation: `https://dev.azure.com/{org}/_usersSettings/tokens`.
+- Minimum scopes: `Code: Read`.
+- SSH: `git@ssh.dev.azure.com:v3/{org}/{project}/{repo}`.
+- Note: Microsoft Entra ID tokens are generally preferred over PATs in enterprise environments.
+- Credential helper: Git Credential Manager via `git-credential-manager configure`.
+- Legacy host note: Azure DevOps may also appear under `*.visualstudio.com` URLs.
+
+## Gitea / Forgejo
+
+- CLI: `tea login add` is available but optional and not universally installed.
+- PAT creation: `https://{host}/user/settings/applications`.
+- Minimum scopes: `repo`.
+- SSH: `git@{host}:owner/repo.git`.
+- Note: Forgejo commonly mirrors the same applications-token path and PAT model as Gitea.
+- Note: Some self-hosted instances rename scopes or disable API token creation, so confirm the instance policy if `repo` is rejected.
+
+## Generic Git (Self-Hosted)
+
+- Platform CLI: None assumed.
+- Auth path: Prefer SSH keys first, then PAT if the host documents HTTPS token auth.
+- PAT creation: Ask the user for the platform's PAT or application-token settings URL.
+- SSH: Use the host's documented SSH remote format; do not assume GitHub-style shortcuts if the server advertises a different pattern.
+
+## API File-Read Endpoints (for web-based code access)
+
+When agents need to read individual files without cloning, use these authenticated API endpoints.
+
+### GitHub / GitHub Enterprise
+
+```text
+# Read file contents (returns JSON with base64 content)
+GET https://api.github.com/repos/{owner}/{repo}/contents/{path}?ref={branch}
+Authorization: token <PAT>
+
+# GHE: replace api.github.com with <ghe-host>/api/v3
+GET https://<ghe-host>/api/v3/repos/{owner}/{repo}/contents/{path}?ref={branch}
+
+# Or use gh CLI (auto-authenticated):
+gh api repos/{owner}/{repo}/contents/{path}?ref={branch} --jq '.content' | base64 -d
+```
+
+### GitLab / GitLab Self-Managed
+
+```text
+# URL-encode the file path (/ becomes %2F)
+GET https://gitlab.com/api/v4/projects/{project-id}/repository/files/{url-encoded-path}/raw?ref={branch}
+PRIVATE-TOKEN: <PAT>
+
+# Or use project path instead of ID:
+GET https://gitlab.com/api/v4/projects/{url-encoded-namespace%2Fproject}/repository/files/{url-encoded-path}/raw?ref={branch}
+```
+
+### Azure DevOps
+
+```text
+GET https://dev.azure.com/{org}/{project}/_apis/git/repositories/{repo}/items?path={path}&api-version=7.0
+Authorization: Basic {base64(:PAT)}
+```
+
+### Bitbucket Cloud
+
+```text
+GET https://api.bitbucket.org/2.0/repositories/{workspace}/{repo}/src/{commit-or-branch}/{path}
+Authorization: Bearer <app-password-or-token>
+```
+- Note: Self-hosted products often customize auth policy, token names, and minimum scopes.
+
+## Safe Credential Delivery Patterns
+
+| Method | Command | Safety |
+|---|---|---|
+| Platform CLI | `gh auth login` / `glab auth login` | Best — handles credential storage |
+| Git Credential Manager | `git credential-manager configure` | Good — OS keychain storage |
+| Environment variable | `GH_TOKEN=xxx gh repo clone ...` | OK — ephemeral; safer than URL tokens but visible to same-user processes |
+| Git askpass | `GIT_ASKPASS=script git clone ...` | OK — no shell history exposure |
+| Inline in URL | `git clone https://token@host/...` | FORBIDDEN — leaks in history/logs |
+
+## Operational Notes
+
+- Prefer SSH when the user already has working keys and the host advertises a stable SSH remote format.
+- Prefer platform CLI login for GitHub and GitLab because it also wires Git credential storage.
+- Prefer Git Credential Manager for Azure DevOps and other HTTPS-heavy enterprise setups.
+- When recommending PAT creation, always suggest setting a short expiry (7-30 days for task-specific work). Prefer fine-grained or short-lived tokens.
+- Never recommend pasting tokens inline into clone URLs, scripts checked into the repo, or long-lived shell profiles.

package/packages/cli/dist/constants-D93JHBiN.js

@@ -1 +0,0 @@
-const e=`aikit`,t={type:`stdio`,command:`npx`,args:[`-y`,`@vpxa/aikit`,`serve`]},n=[`aikit`,`brainstorming`,`multi-agents-development`,`session-handoff`,`requirements-clarity`,`lesson-learned`,`c4-architecture`,`adr-skill`,`present`,`frontend-design`,`react`,`typescript`,`docs`],r=[`aikit-basic`,`aikit-advanced`,`_epilogue`],i={"chat.agentFilesLocations":{"~/.claude/agents":!1},"github.copilot.chat.copilotMemory.enabled":!0,"chat.customAgentInSubagent.enabled":!0,"chat.useNestedAgentsMdFiles":!0,"chat.useAgentSkills":!0,"github.copilot.chat.switchAgent.enabled":!0,"workbench.browser.enableChatTools":!0,"chat.mcp.apps.enabled":!0,"chat.instructionsFilesLocations":{"~/.copilot/instructions":!0,".github/instructions":!0}};export{i as a,n as i,t as n,e as r,r as t};