Academy
Preview 0.30

Back to the Preview

Recovery guidance

Use this page when an installed Academy command refuses an operation or a lesson result differs from what the page describes. Diagnose first. Preserve the branch, committed evidence, uncommitted work, and command report until the next safe action is clear.

Run this read-only observation before choosing a branch below.

Inspect without changing state

Run the installed Academy Doctor command from the repository. Read the repository path, Git state, current branch, origin, and upstream before taking another action.

Why

The read-only Doctor snapshot keeps repository diagnosis separate from recovery changes; Inspect is a presentation, not another operation.

You · Native terminal · Windows

$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.30\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path doctor

You · Native terminal · macOS

academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" doctor

You · Native terminal · Linux

academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" doctor

Expected result

Doctor reports each available repository boundary and makes no repository change.

If that does not happen

If Doctor cannot identify a Git repository, stop and follow the Repository not found decision below.

Evidence

The report records the state you observed before recovery.

Repository not found or not Git

Stop: Do not create files or start a lesson in the selected folder. Observe: Academy Doctor reports that it cannot find the repository or its Git metadata. Safe action: Return to the Academy Home page, locate the clone created from your fork, enter that folder in a Native terminal, and run Doctor there. Preserved: The folder you selected remains unchanged.

Dirty worktree

Stop: Do not reset or switch branches. Observe: The Doctor snapshot reports the changed and untracked paths. Safe action: Identify which paths are lesson evidence, commit the evidence that is ready, and leave unrelated work on its current branch. Preserved: Every changed file and the current branch remain available for review.

Wrong branch or detached HEAD

Stop: Do not begin another attempt. Observe: The Doctor snapshot names the numbered attempt branch or says that HEAD is detached. Safe action: Copy the exact attempt-branch name from the snapshot into the action below and switch to it; if Doctor names no attempt branch, stop and return to the lesson page instead. Preserved: Existing commits and the detached commit remain reachable.

Return to the named attempt branch

Replace <attempt-branch> with the exact numbered branch printed by the Doctor snapshot, then run the command in a Native terminal. Do not guess a branch name.

Why

Switching to an existing named branch preserves commits and restores the lesson's intended working context.

You · Native terminal · Windows

git switch <attempt-branch>

You · Native terminal · macOS

git switch <attempt-branch>

You · Native terminal · Linux

git switch <attempt-branch>

Expected result

Git reports that the exact numbered attempt branch is checked out and preserves its existing commits.

If that does not happen

If Git refuses because of local changes, do not force the switch; return to the Dirty worktree decision and preserve those paths.

Evidence

A new Doctor snapshot names the intended numbered attempt branch.

Unsafe or missing remotes

Stop: Do not push. Observe: The Doctor snapshot shows any mismatch from this contract: origin fetch and push target your fork, upstream fetches the official repository, remote.upstream.pushurl is DISABLED, and effective push routing resolves to origin. Safe action: Replace YOUR-GITHUB-ACCOUNT in the action below, run the command for your operating system, and run Doctor again before pushing. Preserved: Local branches, commits, and working files do not change when remote configuration is corrected.

Restore the learner-safe remote contract

Replace YOUR-GITHUB-ACCOUNT with the GitHub account that owns your fork, then run the complete variant in a Native terminal from the clone.

Why

The explicit fetch, push, upstream-disable, default, and current-branch settings prevent an inherited push target from bypassing the learner fork.

You · Native terminal · Windows

git config --unset-all remote.origin.url 2>$null
git config --add remote.origin.url https://github.com/YOUR-GITHUB-ACCOUNT/arbiter-academy.git
git config --unset-all remote.origin.pushurl 2>$null
git config --add remote.origin.pushurl https://github.com/YOUR-GITHUB-ACCOUNT/arbiter-academy.git
git config --unset-all remote.upstream.url 2>$null
git config --add remote.upstream.url https://github.com/arbiterForge/arbiter-academy.git
git config --unset-all remote.upstream.pushurl 2>$null
git config --add remote.upstream.pushurl DISABLED
git config remote.pushDefault origin
$branch = git branch --show-current
if ($branch) { git config "branch.$branch.pushRemote" origin }

You · Native terminal · macOS

git config --unset-all remote.origin.url || true
git config --add remote.origin.url https://github.com/YOUR-GITHUB-ACCOUNT/arbiter-academy.git
git config --unset-all remote.origin.pushurl || true
git config --add remote.origin.pushurl https://github.com/YOUR-GITHUB-ACCOUNT/arbiter-academy.git
git config --unset-all remote.upstream.url || true
git config --add remote.upstream.url https://github.com/arbiterForge/arbiter-academy.git
git config --unset-all remote.upstream.pushurl || true
git config --add remote.upstream.pushurl DISABLED
git config remote.pushDefault origin
branch=$(git branch --show-current)
if [ -n "$branch" ]; then git config "branch.$branch.pushRemote" origin; fi

You · Native terminal · Linux

git config --unset-all remote.origin.url || true
git config --add remote.origin.url https://github.com/YOUR-GITHUB-ACCOUNT/arbiter-academy.git
git config --unset-all remote.origin.pushurl || true
git config --add remote.origin.pushurl https://github.com/YOUR-GITHUB-ACCOUNT/arbiter-academy.git
git config --unset-all remote.upstream.url || true
git config --add remote.upstream.url https://github.com/arbiterForge/arbiter-academy.git
git config --unset-all remote.upstream.pushurl || true
git config --add remote.upstream.pushurl DISABLED
git config remote.pushDefault origin
branch=$(git branch --show-current)
if [ -n "$branch" ]; then git config "branch.$branch.pushRemote" origin; fi

Expected result

Doctor reports origin fetch and push on your fork, upstream fetch on the official Academy repository, upstream push disabled, and effective push routing to origin.

If that does not happen

If any command reports an error, stop before pushing, preserve the complete output, and run Doctor again to identify the remaining mismatch.

Evidence

The Doctor snapshot records the complete learner-safe remote contract.

For Check and Reset, the lab-id placeholder means the exact lesson ID printed on the lesson page and embedded between academy/ and the attempt number in the current branch. Replace the whole angle-bracketed placeholder shown in the command card. Use Check only after the Doctor snapshot identifies the intended numbered attempt. Its report is the observation used by the next two branches.

Read the authoritative lesson result

Replace <lab-id> with the lesson ID from the lesson page or current academy/<lab-id>/<attempt> branch, without typing angle brackets. Run Check only after the Doctor snapshot identifies the intended numbered attempt.

Why

The installed Academy checker evaluates the selected repository as untrusted input.

You · Native terminal · Windows

$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.30\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path check <lab-id>

You · Native terminal · macOS

academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" check <lab-id>

You · Native terminal · Linux

academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" check <lab-id>

Expected result

Check either passes or names the exact unmet lesson requirement.

If that does not happen

If there is no prepared attempt, return to the lesson and Prepare once. If Check fails, preserve the report and follow that lesson's recovery text.

Evidence

The Check report belongs with the numbered attempt.

No prepared attempt

Stop: Do not manufacture an attempt branch by hand. Observe: Check reports that no numbered attempt is prepared for the selected lesson. Safe action: Return to that lesson page and run its installed Academy Prepare command once. Preserved: Existing branches and evidence remain untouched.

Failed Check with clean committed evidence

Stop: Do not rewrite the evidence commit. Observe: Check names the unmet requirement while the Doctor snapshot reports a clean worktree. Safe action: Keep the report with the attempt, read the lesson's expected result and recovery text, then make the smallest new correction on the same attempt branch. Preserved: The failed commit and Check report remain part of the evidence trail.

Retry

Stop: Do not retry until the current evidence is committed and the Doctor snapshot reports safe remotes plus a clean worktree. Observe: Check still fails after the documented correction, or the lesson explicitly directs a fresh attempt. Safe action: Run Reset once with the same lesson ID used for Check. Reset archives the current attempt and prepares the next numbered attempt, so do not run Prepare afterward. Preserved: The prior attempt branch and its committed evidence remain available.

Create the next documented attempt

Replace <lab-id> with the same lesson ID used for Check, without typing angle brackets. Run Reset only after the current attempt evidence is committed, the worktree is clean, and the remotes are safe.

Why

Reset keeps the failed attempt and creates the next numbered attempt through one bounded operation.

You · Native terminal · Windows

$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.30\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path reset <lab-id>

You · Native terminal · macOS

academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" reset <lab-id>

You · Native terminal · Linux

academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" reset <lab-id>

Expected result

Academy reports the archived attempt and the next prepared attempt number.

If that does not happen

If Reset refuses, keep the current state, run Doctor, and resolve only the condition it reports.

Evidence

Both numbered attempt branches remain available.

Return to main

Stop: Do not leave an attempt while it has uncommitted work. Observe: Check has examined the committed evidence and the Doctor snapshot reports a clean worktree on the numbered attempt branch. Safe action: Run the native-terminal handoff below. Its preflight verifies the clean worktree, numbered attempt branch, and local main before git switch main; it does not call a nonexistent Academy return-to-base route. Preserved: The attempt branch, its commits, and its Check evidence remain intact.

Return to the course base

Run this native-terminal handoff only after Check has examined committed evidence. It refuses unless the worktree is clean, the current branch is a numbered Academy attempt, and local main exists.

Why

The preflight leaves the numbered attempt branch and its commits intact, then uses the already taught git switch main command without inventing an Academy route.

You · Native terminal · Windows

$changes = git status --porcelain
if ($LASTEXITCODE -ne 0 -or $changes) { throw "Return to main requires a clean Git worktree." }
$attempt = git branch --show-current
if ($LASTEXITCODE -ne 0 -or $attempt -notmatch '^academy/[A-Z][0-9]{2}-[A-Za-z0-9-]+/[0-9]+$') { throw "Return to main requires a numbered Academy attempt branch." }
git show-ref --verify --quiet refs/heads/main
if ($LASTEXITCODE -ne 0) { throw "Return to main requires a local main branch." }
git switch main

You · Native terminal · macOS

test -z "$(git status --porcelain)" || { printf '%s\n' 'Return to main requires a clean Git worktree.' >&2; exit 1; }
attempt=$(git branch --show-current)
printf '%s\n' "$attempt" | grep -Eq '^academy/[A-Z][0-9]{2}-[A-Za-z0-9-]+/[0-9]+$' || { printf '%s\n' 'Return to main requires a numbered Academy attempt branch.' >&2; exit 1; }
git show-ref --verify --quiet refs/heads/main || { printf '%s\n' 'Return to main requires a local main branch.' >&2; exit 1; }
git switch main

You · Native terminal · Linux

test -z "$(git status --porcelain)" || { printf '%s\n' 'Return to main requires a clean Git worktree.' >&2; exit 1; }
attempt=$(git branch --show-current)
printf '%s\n' "$attempt" | grep -Eq '^academy/[A-Z][0-9]{2}-[A-Za-z0-9-]+/[0-9]+$' || { printf '%s\n' 'Return to main requires a numbered Academy attempt branch.' >&2; exit 1; }
git show-ref --verify --quiet refs/heads/main || { printf '%s\n' 'Return to main requires a local main branch.' >&2; exit 1; }
git switch main

Expected result

Git switches to main while the numbered attempt branch and its commits remain reachable.

If that does not happen

If the preflight refuses, keep the attempt open and resolve only the named dirty-worktree, branch, or missing-main condition; do not force the switch or delete the attempt.

Evidence

The attempt branch and evidence commits remain reachable after returning to main.