@vpxa/aikit 0.1.74 → 0.1.76

package/scaffold/_preview/skills/react/SKILL.md

@@ -1,309 +0,0 @@
----
-name: react
-description: "Comprehensive React development patterns — component architecture, React 19 APIs, Server Components, TypeScript integration, and performance optimization."
-metadata:
-  category: domain
-  domain: react
-  applicability: on-demand
-  inputs: [codebase, requirements]
-  outputs: [component-patterns, code]
-  relatedSkills: [typescript, frontend-design]
----
-
-# React
-
-> Comprehensive React development patterns — component architecture, React 19 APIs, Server Components, TypeScript integration, and performance optimization. Synthesized from react-dev patterns, react-patterns (React 19), and Vercel React best practices.
-
-## When to Use
-
-**MANDATORY** for the Frontend agent on every React task. Also use when:
-- Building React components, hooks, or pages
-- Working with Server Components or Server Actions
-- Optimizing React performance (re-renders, bundle size, data fetching)
-- Reviewing React code for correctness and best practices
-
-## React 19 Quick Reference
-
-| API | Use Case | Key Change |
-|-----|----------|------------|
-| `ref` as prop | Access DOM/component instance | No more `forwardRef` wrapper |
-| `use()` | Read promises/context in render | Replaces `useContext`, enables async |
-| `useActionState` | Form submission state + error | Replaces `useFormState` |
-| `useOptimistic` | Instant UI feedback | Optimistic updates before server confirms |
-| `useTransition` | Non-urgent state updates | `isPending` for loading states |
-| `<form action>` | Server Actions in forms | Direct server function binding |
-| Server Components | Zero-bundle components | Default in App Router, no `"use client"` |
-| Server Actions | Server mutations | `"use server"` functions, form actions |
-
-## Component Patterns
-
-### Extend Native Elements
-```tsx
-type ButtonProps = React.ComponentProps<"button"> & {
-  variant?: "primary" | "secondary" | "ghost";
-  size?: "sm" | "md" | "lg";
-};
-
-function Button({ variant = "primary", size = "md", className, ...props }: ButtonProps) {
-  return <button className={cn(variants[variant], sizes[size], className)} {...props} />;
-}
-```
-
-### Discriminated Union Props
-```tsx
-type ModalProps =
-  | { variant: "alert"; message: string; onConfirm: () => void }
-  | { variant: "form"; children: React.ReactNode; onSubmit: (data: FormData) => void };
-
-function Modal(props: ModalProps) {
-  switch (props.variant) {
-    case "alert": return <AlertModal {...props} />;
-    case "form": return <FormModal {...props} />;
-  }
-}
-```
-
-### Generic Components
-```tsx
-type TableProps<T> = {
-  data: T[];
-  columns: { key: keyof T; header: string; render?: (value: T[keyof T], row: T) => React.ReactNode }[];
-  onRowClick?: (row: T) => void;
-};
-
-function Table<T extends Record<string, unknown>>({ data, columns, onRowClick }: TableProps<T>) {
-  // ...
-}
-```
-
-### Children Typing
-```tsx
-// Specific children
-type Props = { children: React.ReactElement<TabProps>[] };
-
-// Render function children
-type Props = { children: (data: T) => React.ReactNode };
-
-// String only
-type Props = { children: string };
-```
-
-## Ref as Prop (React 19)
-
-```tsx
-// React 19: pass ref directly, no forwardRef needed
-function Input({ ref, ...props }: React.ComponentProps<"input">) {
-  return <input ref={ref} {...props} />;
-}
-
-// Cleanup function (new in React 19)
-function MeasuredDiv({ ref, ...props }: React.ComponentProps<"div">) {
-  return (
-    <div
-      ref={(node) => {
-        if (node) measureElement(node);
-        return () => cleanupMeasurement(); // cleanup on unmount
-      }}
-      {...props}
-    />
-  );
-}
-```
-
-## Server Components & Actions
-
-### Server Component (default — no directive needed)
-```tsx
-// app/users/page.tsx — Server Component (default)
-import { db } from "@/lib/db";
-
-export default async function UsersPage() {
-  const users = await db.query.users.findMany();  // Direct DB access
-  return <UserList users={users} />;  // Pass data to client
-}
-```
-
-### Client Component (explicit opt-in)
-```tsx
-"use client";
-import { useState, useOptimistic, useTransition } from "react";
-
-export function Counter({ initialCount }: { initialCount: number }) {
-  const [count, setCount] = useState(initialCount);
-  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
-}
-```
-
-### Server Action with Form
-```tsx
-// actions.ts
-"use server";
-import { z } from "zod";
-
-const schema = z.object({ name: z.string().min(1), email: z.string().email() });
-
-export async function createUser(_prev: unknown, formData: FormData) {
-  const result = schema.safeParse(Object.fromEntries(formData));
-  if (!result.success) return { error: result.error.flatten().fieldErrors };
-  await db.insert(users).values(result.data);
-  return { success: true };
-}
-```
-
-```tsx
-"use client";
-import { useActionState } from "react";
-import { createUser } from "./actions";
-
-export function CreateUserForm() {
-  const [state, action, isPending] = useActionState(createUser, null);
-  return (
-    <form action={action}>
-      <input name="name" required />
-      {state?.error?.name && <p className="text-red-500">{state.error.name}</p>}
-      <input name="email" type="email" required />
-      {state?.error?.email && <p className="text-red-500">{state.error.email}</p>}
-      <button disabled={isPending}>{isPending ? "Creating..." : "Create"}</button>
-    </form>
-  );
-}
-```
-
-### Optimistic Updates
-```tsx
-"use client";
-import { useOptimistic } from "react";
-
-function TodoList({ todos, addTodo }: { todos: Todo[]; addTodo: (text: string) => Promise<void> }) {
-  const [optimisticTodos, addOptimistic] = useOptimistic(
-    todos,
-    (state, newTodo: string) => [...state, { id: "temp", text: newTodo, pending: true }]
-  );
-
-  async function handleAdd(formData: FormData) {
-    const text = formData.get("text") as string;
-    addOptimistic(text);
-    await addTodo(text);
-  }
-
-  return (
-    <form action={handleAdd}>
-      <input name="text" />
-      <button type="submit">Add</button>
-      <ul>
-        {optimisticTodos.map(t => (
-          <li key={t.id} style={{ opacity: t.pending ? 0.5 : 1 }}>{t.text}</li>
-        ))}
-      </ul>
-    </form>
-  );
-}
-```
-
-## Event Handler Types
-
-```tsx
-// Always use specific event types
-onClick:    (e: React.MouseEvent<HTMLButtonElement>) => void
-onChange:   (e: React.ChangeEvent<HTMLInputElement>) => void
-onSubmit:   (e: React.FormEvent<HTMLFormElement>) => void
-onKeyDown:  (e: React.KeyboardEvent<HTMLInputElement>) => void
-onFocus:    (e: React.FocusEvent<HTMLInputElement>) => void
-onDrag:     (e: React.DragEvent<HTMLDivElement>) => void
-```
-
-## Hooks Typing
-
-```tsx
-// useState with union
-const [status, setStatus] = useState<"idle" | "loading" | "error">("idle");
-
-// useRef for DOM — pass null, get RefObject
-const inputRef = useRef<HTMLInputElement>(null);
-
-// useRef for mutable value — no null, get MutableRefObject
-const intervalRef = useRef<number>(0);
-
-// useReducer with discriminated actions
-type Action = { type: "increment" } | { type: "set"; payload: number };
-const [count, dispatch] = useReducer((state: number, action: Action) => {
-  switch (action.type) {
-    case "increment": return state + 1;
-    case "set": return action.payload;
-  }
-}, 0);
-
-// Custom hook: return as const for tuple types
-function useToggle(initial = false) {
-  const [value, setValue] = useState(initial);
-  const toggle = useCallback(() => setValue(v => !v), []);
-  return [value, toggle] as const;
-}
-
-// useContext with null guard
-const ctx = useContext(ThemeContext);
-if (!ctx) throw new Error("useTheme must be used within ThemeProvider");
-```
-
-## Performance Rules
-
-### Prevent Async Waterfalls
-```tsx
-// BAD — sequential fetching
-const user = await getUser(id);
-const posts = await getPosts(user.id);  // Waits for user first
-const comments = await getComments(posts[0].id);  // Waits for posts
-
-// GOOD — parallel where possible
-const [user, posts] = await Promise.all([getUser(id), getPosts(id)]);
-```
-
-### Bundle Size
-- `dynamic(() => import("./HeavyComponent"))` — lazy load below-fold components
-- Tree-shake: use named exports, avoid `import *`
-- Analyze bundle: `@next/bundle-analyzer` to find bloat
-- Code-split by route — each page loads only its own JS
-- Avoid importing entire libraries: `import { debounce } from "lodash-es"` not `import _ from "lodash"`
-
-### Server-Side Performance
-- Default to Server Components — zero JS shipped to client
-- Stream with Suspense: wrap slow data fetchers in `<Suspense fallback={<Skeleton />}>`
-- Cache expensive computations with `"use cache"` directive
-- Avoid serializing large objects across server/client boundary
-
-### Client-Side Data Fetching
-- Use SWR or React Query — automatic caching, revalidation, error retry
-- Stale-while-revalidate: show cached data instantly, refresh in background
-- Error boundaries: `<ErrorBoundary>` wrapping data-dependent trees
-- Prefetch on hover/viewport for likely next navigations
-
-### Re-render Optimization
-- React Compiler (React 19): auto-memoizes — try this first before manual `useMemo`/`useCallback`
-- If no compiler: `useMemo` for expensive computations, `useCallback` for stable function references
-- Extract static JSX outside components — constants don't re-create
-- Split context: separate frequently-changing state from rarely-changing state
-- `React.memo()` on components receiving only primitive props
-
-### Rendering Performance
-- **Virtualize** lists > 100 items: `@tanstack/react-virtual`, `react-window`
-- Defer heavy computations with `useDeferredValue`
-- Batch state updates (React 18+ does this automatically in event handlers)
-- Avoid reading DOM layout during renders (force sync layout = jank)
-
-### Advanced Patterns
-- Progressive hydration: load and hydrate components as they enter viewport
-- Concurrent features: `useTransition` for non-blocking state updates
-- Suspense caching: combine `<Suspense>` with data cache for instant page transitions
-- React Compiler adoption: enable gradually, check for unsafe patterns first
-
-## Decision Flow
-
-When implementing a React feature:
-
-1. **Server or Client?** → If it uses browser APIs, event handlers, or useState → Client. Everything else → Server.
-2. **Data fetching?** → Server Component for initial data. SWR/React Query for client-side mutations.
-3. **Form?** → Server Action + `useActionState` + Zod validation.
-4. **Optimistic?** → `useOptimistic` for instant feedback.
-5. **Loading?** → `<Suspense>` with skeleton fallback.
-6. **Performance?** → Try React Compiler first. Then manual memo. Then virtualization. Then code splitting.
-7. **Error?** → Error boundaries for rendering errors. try/catch for Server Actions.

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

@@ -1,178 +0,0 @@
----
-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/_preview/skills/repo-access/references/error-patterns.md

@@ -1,116 +0,0 @@
-# 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.