# Apollo 11 AGC Source User Guide

The original Apollo 11 guidance computer (AGC) source code, as flown on July 20, 1969. The `chrislgarry/Apollo-11` repository preserves the **Comanche055** program (Command Module Computer) and the **Luminary099** program (Lunar Module Guidance Computer), digitised from MIT Museum hardcopies and continuously proof-read against the original scanned printouts.

This guide shows you how to find, read, search, simulate, and contribute corrections to the source. It is for software historians, programmers, embedded-systems students, NASA enthusiasts, and anyone who wants to study the actual software that landed humans on the Moon.

> [!NOTE]
> The repository is a **historical archive**, not an active software product. The code itself dates from 1969 and is in the public domain. The repository's day-to-day work is **proof-reading transcriptions** against the original scanned printouts.

---

## 1. Quick Start

There is nothing to install. The `.agc` files are plain text and GitHub renders them with native syntax highlighting. The shortest path to value is to open the repository in your browser.

1. Visit [github.com/chrislgarry/Apollo-11](https://github.com/chrislgarry/Apollo-11).
2. Open the `Luminary099/` directory — this is the **Lunar Module** flight program.
3. Click `THE_LUNAR_LANDING.agc`. You are now reading the routine that flew Eagle from lunar orbit to Tranquility Base.
4. Open `Comanche055/` and click `CONTRACT_AND_APPROVALS.agc` to see Margaret Hamilton's sign-off block from 28 March 1969.

> [!TIP]
> No clone, no toolchain, no editor extension required. GitHub's `.agc` highlighting and the in-tree `README.md` files inside `Comanche055/` and `Luminary099/` index every section by original printout page number — the fastest way to navigate is the program README.

If you want a local copy:

```bash
git clone https://github.com/chrislgarry/Apollo-11.git
cd Apollo-11
ls Comanche055 Luminary099
```

```text
Comanche055/  AGC_BLOCK_TWO_SELF-CHECK.agc  ALARM_AND_ABORT.agc  ANGLFIND.agc  ...
Luminary099/  AGC_BLOCK_TWO_SELF_CHECK.agc  AGS_INITIALIZATION.agc  ALARM_AND_ABORT.agc  ...
```

To **assemble and run** the code (turning these listings into a binary that executes on a simulated AGC), you need the separate **Virtual AGC** project. See Section 2.

To **contribute proof-reading corrections**, see Section 5.

### What you'll find in the next 30 seconds

- `Luminary099/THE_LUNAR_LANDING.agc` — `P63` (powered descent) and `P64` (visibility phase).
- `Luminary099/LUNAR_LANDING_GUIDANCE_EQUATIONS.agc` — the actual landing maths.
- `Comanche055/P11.agc` — Earth orbit insertion monitor.
- `Comanche055/P61-P67.agc` — atmospheric reentry guidance.
- `Comanche055/CONTRACT_AND_APPROVALS.agc` — the team that signed off the program in 1969.
- `Luminary099/BURN_BABY_BURN--MASTER_IGNITION_ROUTINE.agc` — yes, that is the real filename.

---

## 2. Installation

There is nothing to install for **reading** the source. The repository ships only `.agc` text files and Markdown documentation. Reading is a `git clone` (or no clone at all — read on GitHub directly).

For **assembling and simulating** the code, install the Virtual AGC toolchain. Virtual AGC is a separate project that provides:

- `yaYUL` — a modern re-implementation of the original 1969 YUL/GAP assembler.
- `yaAGC` — a faithful AGC simulator.
- `yaDSKY2` — a graphical DSKY (Display/Keyboard) astronaut interface.

> [!IMPORTANT]
> The simulator is maintained by the **Virtual AGC** project ([virtualagc/virtualagc](https://github.com/virtualagc/virtualagc)), not by this repository. Build instructions, supported platforms, and dependency lists live in that project's README. The instructions below are the canonical entry path; defer to upstream for current details.

### 2.1 Read-only install (browse and grep)

| Method | Command |
| :--- | :--- |
| Clone via HTTPS | `git clone https://github.com/chrislgarry/Apollo-11.git` |
| Clone via SSH | `git clone git@github.com:chrislgarry/Apollo-11.git` |
| Download ZIP | Click **Code → Download ZIP** on the GitHub web page |
| GitHub Codespaces | Click **Code → Codespaces → Create codespace** for a browser shell |

System requirements for read-only use are minimal: any system that can store ~30 MB of text and run `git`, `grep`, or `less`. No build tools, no Node, no Python.

### 2.2 Toolchain install (assemble and simulate)

```bash
# Linux / macOS — build Virtual AGC from source
git clone https://github.com/virtualagc/virtualagc.git
cd virtualagc
make
```

> [!WARNING]
> Native Windows builds of Virtual AGC are non-trivial. Use **WSL2** (Ubuntu) and follow the Linux instructions, or download a pre-built release from the Virtual AGC project's releases page. Native MinGW builds are documented in the Virtual AGC README but require manual dependency setup.

### 2.3 Markdown lint install (for translation contributions only)

If you intend to update or add a translation in `Translations/`, install the lint dependency before opening a PR:

```bash
cd Apollo-11
npm install
npm run lint
```

The repository ships `bun.lockb`, indicating the maintainer uses [Bun](https://bun.sh/). `bun install && bun run lint` works equivalently and is faster.

```text
markdownlint-cli2 v0.16.0 ()
Finding: *.md translations/*.md Comanche055/*.md Luminary099/*.md
```

> [!NOTE]
> Markdown linting is needed only for `.md` documentation changes. Proof-reading PRs that touch `.agc` files do not require any toolchain — the maintainer reviews them by eye against the scans.

### 2.4 Verify the install

Whether reading or assembling, the easiest sanity check is to print the header of any source file:

```bash
head -15 Luminary099/THE_LUNAR_LANDING.agc
```

```text
# Copyright:   Public domain.
# Filename:    THE_LUNAR_LANDING.agc
# Purpose:     Part of the source code for Luminary 1A build 099.
#              It is part of the source code for the Lunar Module's (LM)
#              Apollo Guidance Computer (AGC), for Apollo 11.
# Assembler:   yaYUL
# Contact:     Hartmuth Gutsche <[email removed]>.
# Website:     www.ibiblio.org/apollo.
# Pages:       785-792
# Mod history: 2009-05-20 HG  Transcribed from page images.
```

If you see a copyright/provenance block in this exact shape, the file is intact and ready to read.

---

## 3. Configuration

There is no runtime configuration: the repository is plain text source code, not a service. The only configuration files in the tree govern **editor behaviour** and **markdown linting** for contributors.

### 3.1 `.editorconfig`

Sets the canonical AGC formatting that every editor must respect:

```ini
root = true

[*]
indent_style = tab
indent_size = 8
trim_trailing_whitespace = true
```

Tab indentation with width 8 matches the original 1969 printout convention. Any modern editor that respects `.editorconfig` (most do) will pick this up automatically.

> [!IMPORTANT]
> Do not let your editor convert tabs to spaces or strip the `R0000` line-break markers in column 1. Either change will produce whitespace-only diffs that bury the real fix and make the PR much harder to review.

### 3.2 `.markdownlint.yml`

Disables ten default markdown rules that conflict with the multilingual / historical-attribution / table-heavy nature of the documentation:

```yaml
default: true
MD007: false   # ul-indent
MD010: false   # no-hard-tabs
MD013: false   # line-length
MD026: false   # no-trailing-punctuation in headings
MD033: false   # no-inline-html
MD034: false   # no-bare-urls
MD036: false   # no-emphasis-as-heading
MD041: false   # first-line-h1
MD050: false   # strong-style
MD053: false   # link-image-reference-definitions
```

| Rule | Why disabled |
| :--- | :--- |
| `MD013` (line length) | Translation lines and attribution tables are intentionally long |
| `MD033` (no inline HTML) | Some translations use HTML for RTL languages |
| `MD034` (no bare URLs) | Translation links in the README header are bare by design |
| `MD041` (first line H1) | Several translations open with a TOC table |
| `MD050` (strong style) | Translations use varying bold conventions |

### 3.3 `package.json`

The lint scripts are the only "build" commands in the entire repository:

```json
{
  "scripts": {
    "lint": "markdownlint-cli2 *.md translations/*.md Comanche055/*.md Luminary099/*.md --config .markdownlint.yml",
    "lint:fix": "markdownlint-cli2 *.md translations/*.md Comanche055/*.md Luminary099/*.md --config .markdownlint.yml --fix"
  },
  "devDependencies": {
    "markdownlint-cli2": "^0.16.0"
  }
}
```

> [!TIP]
> The `translations/*.md` glob is lower-case but the directory in the repository is `Translations/` (capitalised). On case-sensitive filesystems some lint runs may not match the translations folder. If you want full coverage, run `npx markdownlint-cli2 'Translations/*.md'` separately.

There are no runtime environment variables, no config flags for `yaYUL` consumed from this repo, no dotenv files.

---

## 4. Core Usage

This section explains the directory layout, the assembly-language conventions, and how to read a `.agc` file end-to-end.

### 4.1 Directory layout

The repository has **three** content directories plus a small set of root-level documentation files:

```text
Apollo-11/
├── Comanche055/                 80 .agc files (Command Module program)
├── Luminary099/                 86 .agc files (Lunar Module program)
├── Translations/                70 README.<lang>.md / CONTRIBUTING.<lang>.md
├── README.md                    Project overview, attribution, contract block
├── CONTRIBUTING.md              Proof-reading rules
├── LICENSE.md                   Public domain notice
├── package.json                 markdownlint-cli2 lint scripts
├── bun.lockb                    Bun lockfile
├── .markdownlint.yml            Linter configuration (relaxed rules)
├── .editorconfig                Tab indentation, width 8
└── .gitignore                   Standard ignores
```

### 4.2 The two flight programs

| Folder | Program | Computer | Mission role |
| :--- | :--- | :--- | :--- |
| `Comanche055/` | *Colossus 2A* build 055 | Command Module Computer (CMC), aboard *Columbia* | Earth launch monitoring, Trans-Lunar Injection support, mid-course corrections, Trans-Earth Injection, atmospheric reentry, CSM attitude control |
| `Luminary099/` | *Luminary 1A* build 099 | LM Guidance Computer (LGC), aboard *Eagle* | Powered descent (the lunar landing itself), lunar surface attitude control, ascent, rendezvous with the CSM |

> [!NOTE]
> The two programs are *not* the same code. They share an executive, waitlist scheduler, interpreter, IMU services, and DSKY UI, but the **application** layer differs entirely — Comanche handles atmospheric reentry; Luminary handles a vacuum-only powered descent and ascent. Each program also stamps a header line with the exact assembly date.

```text
Comanche055/MAIN-style header:  Assemble revision 055 of AGC program Comanche by NASA
                                2021113-051. 10:28 APR. 1, 1969

Luminary099/MAIN.agc header:    Assemble revision 001 of AGC program LMY99 by NASA 2021112-061
                                16:27 JUL. 14, 1969
```

### 4.3 Source file naming

Each `.agc` file is named after the **subroutine log section** it contains, taken from the original 1969 printout's Table of Contents. The original program was a single monolithic listing; modern transcribers split it into one file per logical section. The full section catalogue with original page numbers lives in each program's `README.md`.

Examples of section names (these are real filenames in the tree):

- `EXECUTIVE.agc` — the cooperative scheduler.
- `WAITLIST.agc` — the timed-task scheduler.
- `INTERPRETER.agc` — the on-board virtual machine for vector/double-precision math.
- `THE_LUNAR_LANDING.agc` — the powered-descent ignition program (Luminary099 only).
- `LUNAR_LANDING_GUIDANCE_EQUATIONS.agc` — the descent guidance maths (Luminary099).
- `BURN_BABY_BURN--MASTER_IGNITION_ROUTINE.agc` — the master-ignition routine.
- `PINBALL_GAME_BUTTONS_AND_LIGHTS.agc` — the DSKY (display/keyboard) driver.

### 4.4 Reading a `.agc` file

Every `.agc` file follows the same structure:

#### 4.4.1 Header block

```text
# Copyright:   Public domain.
# Filename:    THE_LUNAR_LANDING.agc
# Purpose:     Part of the source code for Luminary 1A build 099.
# Assembler:   yaYUL
# Pages:       785-792
# Mod history: 2009-05-20 HG  Transcribed from page images.
```

The `Pages:` field is **load-bearing** for proof-readers — it points back to the original scanned printout. Open the same pages in the [Luminary099 scans](http://www.ibiblio.org/apollo/ScansForConversion/Luminary099/) to compare line by line.

#### 4.4.2 Body

The body is a sequence of:

- **Page-number comments** (`# Page 785`) — anchors back to the printout.
- **Bank directives** (`BANK 32`, `SETLOC F2DPS*32`) — fixed-memory bank assignments.
- **Erasable bank declarations** (`EBANK= E2DPS`) — the data bank in scope.
- **Labels and instructions** in classic two-column assembly:

```text
P63LM       TC      PHASCHNG
            OCT     04024
            TC      BANKCALL        # DO IMU STATUS CHECK ROUTINE R02
            CADR    R02BOTH
            CAF     P63ADRES        # INITIALIZE WHICH FOR BURNBABY
            TS      WHICH
```

The first column is the **label**; the second is the **opcode**; the third is the **operand**; everything after `#` is a comment. AGC opcodes are extremely terse — `TC` is "transfer control", `CA` is "clear and add" (load), `TS` is "transfer to storage" (store), `CCS` is the unique "count, compare, skip" branch instruction.

### 4.5 The verb/noun command surface

Operating the AGC is done through the **DSKY** (DiSplay/KeYboard) using a **verb/noun** language. A verb is the action ("display", "load", "monitor"); a noun is the data on which to act ("velocity", "GMT time", "specific value"). This is implemented across:

| File | Role |
| :--- | :--- |
| `PINBALL_GAME_BUTTONS_AND_LIGHTS.agc` | Keypad scanner, display driver, lamp logic, verb/noun decoder |
| `PINBALL_NOUN_TABLES.agc` | Noun definitions, scaling, units, decimal/octal display rules |
| `EXTENDED_VERBS.agc` | Verbs ≥40 (operator-action verbs) |
| `DISPLAY_INTERFACE_ROUTINES.agc` | Display priority arbitration |

A representative slice from `Luminary099/EXTENDED_VERBS.agc`:

| Verb | Action |
| :--- | :--- |
| `V37` | Change major mode (selects the mission program — V37 E63E runs P63 powered descent) |
| `V49` | Start automatic attitude maneuver |
| `V57` | Permit landing radar updates |
| `V58` | Inhibit landing radar updates |
| `V63` | Sample radar once per second |
| `V69` | Force a hardware restart |
| `V75` | Enable U,V jets during DPS burns |
| `V82` | Request orbit parameter display (R30) |
| `V83` | Request rendezvous parameter display (R31) |
| `V92` | Operate IMU performance test |

> [!TIP]
> Read `EXTENDED_VERBS.agc` and `PINBALL_GAME_BUTTONS_AND_LIGHTS.agc` together to understand how the DSKY operating language works. The pinball file is the keypad/display driver — it scans the keys, decodes verbs/nouns, and lights the warning/status lamps. Yes, that is its real name in 1969.

### 4.6 Mission programs (P-programs) and routines (R-routines)

Mission programs are large state machines that drive a phase of the mission. Routines are reusable subroutines that programs call.

| Class | Examples | Purpose |
| :--- | :--- | :--- |
| **P-program** (CSM) | `P11`, `P20-P25`, `P30-P37`, `P40-P47`, `P51-P53`, `P61-P67` | Mission phase control (orbit, rendezvous, burns, IMU align, reentry) |
| **P-program** (LM) | `P12`, `P20-P25`, `P40-P47`, `P63-P67`, `P70-P71` | Ascent, rendezvous, descent burns, powered descent, abort |
| **R-routine** | `R30`, `R31`, `R60_62`, `R63` | Orbit/rendezvous parameter display, attitude reference |
| **DAP** | `P-AXIS_RCS_AUTOPILOT.agc`, `Q_R-AXIS_RCS_AUTOPILOT.agc`, `DAPIDLER_PROGRAM.agc` | Digital Auto-Pilot (RCS attitude control) |
| **Guidance** | `LUNAR_LANDING_GUIDANCE_EQUATIONS.agc`, `BURN_BABY_BURN--MASTER_IGNITION_ROUTINE.agc` | Trajectory and burn control |
| **Navigation** | `KALMAN_FILTER.agc`, `MEASUREMENT_INCORPORATION.agc`, `INTEGRATION_INITIALIZATION.agc` | State-vector update from sensor data |
| **Hardware** | `T4RUPT_PROGRAM.agc`, `KEYRUPT_UPRUPT.agc`, `IMU_MODE_SWITCHING_ROUTINES.agc` | Interrupt service routines, IMU drivers |

> [!NOTE]
> The most famous Luminary099 file is `THE_LUNAR_LANDING.agc` (pages 785–792), which contains the powered-descent ignition program **P63** that ran during the final landing. The companion file `LUNAR_LANDING_GUIDANCE_EQUATIONS.agc` (pages 798–828) contains the actual guidance maths.

### 4.7 Editor support

There is no IDE for AGC, but several editors have community syntax-highlighting packages:

| Editor | Extension | Auto-format |
| :--- | :--- | :--- |
| Visual Studio Code | [agc-assembly](https://github.com/wopian/agc-assembly) | Yes |
| Sublime Text 3 | [AGC-Assembly](https://github.com/jimlawton/AGC-Assembly) | Yes |
| Atom | [language-agc](https://github.com/Alhadis/language-agc) | Yes |
| Vim | [vim-assembly](https://github.com/wsdjeg/vim-assembly) | No |
| Eclipse | [Virtual AGC contrib](https://github.com/virtualagc/virtualagc/tree/master/Contributed/SyntaxHighlight/Eclipse) | No |
| jEdit | [Virtual AGC contrib](https://github.com/virtualagc/virtualagc/tree/master/Contributed/SyntaxHighlight/jEdit) | No |
| Code::Blocks | [Virtual AGC contrib](https://github.com/virtualagc/virtualagc/tree/master/Contributed/SyntaxHighlight/CodeBlocks) | No |
| Kate | [Virtual AGC contrib](https://github.com/virtualagc/virtualagc/tree/master/Contributed/SyntaxHighlight/Kate) | No |

> [!TIP]
> If you plan to contribute proof-reading fixes, install one of the **auto-format** options (the top three rows above). They enforce the correct indentation rules — tabs at width 8, trim trailing whitespace — automatically.

---

## 5. Common Tasks

### 5.1 Find a specific routine

Use `grep` against the program directory to locate a routine by label:

```bash
# Find the file that contains powered-descent ignition
grep -rln "^P63LM\|^P63 " Luminary099/
```

```text
Luminary099/THE_LUNAR_LANDING.agc
```

```bash
# Find the alarm-and-abort handler for a specific code
grep -rn "ALARM" Luminary099/ALARM_AND_ABORT.agc | head -10
```

```bash
# Find every interpretive opcode usage of VLOAD
grep -rn "VLOAD" Luminary099/ | head -20
```

### 5.2 Learn AGC architecture from the source

Read these in order to walk through the operating-system layer:

1. `EXECUTIVE.agc` — task scheduling and priorities (the cooperative scheduler).
2. `WAITLIST.agc` — timed-task list (interrupt-driven scheduler).
3. `INTERRUPT_LEAD_INS.agc` — interrupt vector table at fixed address `4000`.
4. `T4RUPT_PROGRAM.agc` — the ~10 ms display/keyboard timer interrupt.
5. `KEYRUPT_UPRUPT.agc` — keypress and uplink interrupts.
6. `RESTARTS_ROUTINE.agc` + `FRESH_START_AND_RESTART.agc` — fault-tolerant restart logic.

> [!NOTE]
> The famous **1201** ("no VAC areas") and **1202** ("no core sets") alarms during Apollo 11's descent are restart-overflow alarms handled here. The restart logic re-issued the active mission program (P63 then P64) without losing position/velocity state — the descent continued to a successful landing because the restart system worked exactly as designed.

### 5.3 Walk through the lunar landing

Open these files in order while reading [the original mission timeline](https://www.nasa.gov/mission_pages/apollo/missions/apollo11.html):

1. `Luminary099/P40-P47.agc` — Powered Descent Initiate (PDI) preparations.
2. `Luminary099/THE_LUNAR_LANDING.agc` — P63 (braking phase), P64 (visibility phase).
3. `Luminary099/LUNAR_LANDING_GUIDANCE_EQUATIONS.agc` — the guidance maths.
4. `Luminary099/THROTTLE_CONTROL_ROUTINES.agc` — descent-engine throttle control.
5. `Luminary099/SERVICER.agc` — 2-second navigation/guidance update cycle.
6. `Luminary099/P70-P71.agc` — DPS / APS abort programs (in case landing fails).

### 5.4 Simulate the code with Virtual AGC

Once Virtual AGC is built and `yaYUL`, `yaAGC`, `yaDSKY2` are on your `PATH`:

```bash
cd /path/to/Apollo-11/Luminary099
yaYUL --html MAIN.agc
```

The assembler walks the `$<filename>` include directives in `MAIN.agc` (yaYUL include syntax), produces a binary core-rope image, and emits an HTML cross-reference listing.

```bash
yaAGC --core=MAIN.bin &
yaDSKY2
```

You can then enter `V37 E63E` on the simulated DSKY to begin powered descent — exactly as Buzz Aldrin did on July 20, 1969 (with substantially different state-vector inputs).

> [!CAUTION]
> The simulator is a faithful re-creation of the AGC opcodes and DSKY UI, but real flight data, RADAR inputs, and IMU drift are not present. The code will execute and respond to DSKY input; full landing simulations require the test fixtures shipped with Virtual AGC.

### 5.5 Study the famous "1202 alarm" code path

The 1202 alarm fired multiple times during the final approach. Walk the path that triggered and recovered from it:

1. `Luminary099/EXECUTIVE.agc` — read the `NOVAC` and `FINDVAC` entry points and look for the overflow check that posts an alarm. The cause is **VAC-area exhaustion** (1202) or **core-set exhaustion** (1201).
2. `Luminary099/ALARM_AND_ABORT.agc` — the routine that posts the alarm code on the DSKY and decides whether to abort.
3. `Luminary099/RESTARTS_ROUTINE.agc` — the recovery path that re-issues the active program from its last good phase.
4. `Luminary099/PHASE_TABLE_MAINTENANCE.agc` — the redundant phase-number storage that the restart consults.
5. `Luminary099/FRESH_START_AND_RESTART.agc` — the cold-start vector and the warm-restart entry.

> [!IMPORTANT]
> The alarms occurred because spurious rendezvous-radar interrupts overloaded the executive's VAC pool. The restart logic re-validated phase tables, killed broken jobs, and resumed P63 (then P64) within milliseconds. This is the most-studied piece of fault-tolerant systems engineering in spaceflight history.

### 5.6 Contribute a comment annotation (proof-reading PR)

The repository's primary work is reconciling the digital transcription with the original scanned printouts. Discrepancies — even single typos or whitespace differences — are valid pull requests.

The proof-reading rule (from `CONTRIBUTING.md`):

> Comments in the transcribed code **MUST** match the scans **exactly** — including original typos, spacing, and line breaks.

| Program | Scans URL |
| :--- | :--- |
| Comanche055 | <http://www.ibiblio.org/apollo/ScansForConversion/Comanche055/> |
| Luminary099 | <http://www.ibiblio.org/apollo/ScansForConversion/Luminary099/> |
| Side-by-side viewer | <https://28gpc.csb.app/> |

```bash
git clone https://github.com/<your-user>/Apollo-11.git
cd Apollo-11
git checkout -b proof/luminary099-pXXX

# Edit files. Match the scans exactly.

git add Luminary099/<file>.agc
git commit -m "Proof Luminary099 page XXX: <short description>"
git push origin proof/luminary099-pXXX
```

Open a pull request against `chrislgarry/Apollo-11:master`.

> [!IMPORTANT]
> Reference the **page number** of the scan in your commit message and PR body. Maintainers verify by opening that page side-by-side with your diff. Without the page reference, the PR is much slower to review.

#### Open proof-reading campaigns

Several files have explicit GitHub issues open for proof-reading work (issue numbers as of commit `247dd7d`):

- [#608](https://github.com/chrislgarry/Apollo-11/issues/608) — Proof `MEASUREMENT_INCORPORATION.agc`
- [#217](https://github.com/chrislgarry/Apollo-11/issues/217) — Proof `INTERPRETER.agc`
- [#566](https://github.com/chrislgarry/Apollo-11/issues/566) — Proof `AOTMARK.agc`
- [#234](https://github.com/chrislgarry/Apollo-11/issues/234) — Proof `P34-35_P74-75.agc`
- [#204](https://github.com/chrislgarry/Apollo-11/issues/204) — Proof `ERASABLE_ASSIGNMENTS.agc`
- [#639](https://github.com/chrislgarry/Apollo-11/issues/639) — Proof `SPS_BACK-UP_RCS_CONTROL.agc`
- [#648](https://github.com/chrislgarry/Apollo-11/issues/648) — Proof `TJET_LAW.agc`
- [#647](https://github.com/chrislgarry/Apollo-11/issues/647) — Proof `TIME_OF_FREE_FALL.agc`
- [#960](https://github.com/chrislgarry/Apollo-11/issues/960) — Add line-by-line validation tests against original scanned documents

#### Proof-reading checklist

- [ ] Open the scanned page next to your edit.
- [ ] Verify every comment character-for-character (typos preserved).
- [ ] Verify spaces match (single between words, double between sentences).
- [ ] Verify line breaks match (`R0000` markers in column 1 are kept).
- [ ] Re-run the markdown linter if you edited a `README.md` (`npm run lint`).
- [ ] Cite the page number in your commit message.

---

## 6. Troubleshooting

### Error: `yaYUL: command not found`

**Cause:** Virtual AGC is not built or not on your `PATH`.

**Solution:** Build Virtual AGC from source ([virtualagc/virtualagc](https://github.com/virtualagc/virtualagc)) and add the `yaAGC/` and `yaYUL/` directories to `PATH`. Or download a pre-built Virtual AGC release.

**Prevention:** Verify with `which yaYUL` before assembly. If empty, fix `PATH` first.

### Error: assembler reports `Unrecognized opcode "..."` on a known-good file

**Cause:** Either (a) you are using an older `yaYUL` version that does not support a directive used in this transcription, or (b) the file has been corrupted (CRLF line endings on Windows are the most common culprit).

**Solution:** Update Virtual AGC from the latest `master`. If the issue persists, run `dos2unix Luminary099/<file>.agc` to normalise line endings, then re-assemble.

**Prevention:** Configure git with `core.autocrlf=input` on Windows so checkouts use Unix line endings.

### Error: `markdownlint-cli2` reports many MD013 (line length) violations

**Cause:** You are linting outside the repository, where the `.markdownlint.yml` config (which disables MD013) is not picked up.

**Solution:** Always run `npm run lint` from the repository root. The `--config .markdownlint.yml` flag in `package.json` ensures the local config is used.

**Prevention:** Use the `npm run lint` script rather than calling `markdownlint-cli2` directly.

### Issue: My PR diff shows whitespace-only changes I did not make

**Cause:** Your editor stripped trailing whitespace, changed tabs to spaces, or normalised line endings on save.

**Solution:** Configure your editor per `.editorconfig`: tab indentation, tab width 8, trim trailing whitespace, and **preserve LF line endings**. Re-clone and re-apply your changes if the diff is unfixable.

**Prevention:** Install one of the auto-formatting editor extensions from Section 4.7.

### Issue: GitHub renders my `.agc` file as plain text

**Cause:** GitHub's syntax highlighter detects AGC by the `.agc` extension. If you renamed the file or added a non-standard extension, highlighting drops.

**Solution:** Restore the `.agc` extension. Do not rename source files.

**Prevention:** Treat the file naming convention (`SUBROUTINE_LOG_SECTION.agc`) as a hard rule — it matches the original printout layout.

### Issue: I cannot find `MAIN.agc` for Comanche055

**Cause:** Comanche055's master include file may use a different name or its includes may be embedded in `ASSEMBLY_AND_OPERATION_INFORMATION.agc`. The two programs were transcribed separately and use slightly different conventions. (Luminary099 has an explicit `MAIN.agc`.)

**Solution:** Open `Comanche055/README.md` — the *Source Code Index* lists the include order. Refer to Virtual AGC's `Comanche055/` mirror for the canonical entry point if it differs.

**Prevention:** Always read the program's `README.md` before assembling.

### Issue: A line ends with `R0000` and I am unsure what that means

**Cause:** `R0000` in column 1 marks a logical "page-marker" continuation in the original printout layout. It is related to the unprinted column-8 digits (`2` = double space, `3` = triple space) used by the original GAP assembler.

**Solution:** Match the scan exactly. Do not strip `R0000` markers. Their presence is significant for proof-reading line-break fidelity.

**Prevention:** Read [CONTRIBUTING.md](https://github.com/chrislgarry/Apollo-11/blob/master/CONTRIBUTING.md) "Line breaks" section before editing line-break-sensitive files.

### Issue: My code-improvement PR was closed without merge

**Cause:** The repository accepts **proof-reading corrections only**. PRs that "modernise" or "improve" the original 1969 code are out of scope.

**Solution:** Re-scope the change as a transcription correction (cite the scan page) or take it to [virtualagc/virtualagc](https://github.com/virtualagc/virtualagc), which is the active simulation/development project.

**Prevention:** Read the project README and CONTRIBUTING.md before opening a PR — the historical-archive policy is the first thing both documents establish.

### Issue: My translation PR fails the lint step

**Cause:** Markdownlint applies the relaxed `.markdownlint.yml` rules; if you added rules locally or edited the wrong glob, the lint may surface false positives.

**Solution:** Run `npm run lint` from the repository root. If a rule fails legitimately, fix the markdown; if it fails because of a translation-specific construct, document the case in the PR and the maintainer can decide whether to relax further.

**Prevention:** Always lint locally before pushing. The lint runs fast (one second on a modern machine).

---

## 7. FAQ

**Q: Can I use this code in my own project?**

Yes. The Apollo Guidance Computer source code is in the **public domain**. NASA software written under government contract before 1978 has no copyright protection in the United States. You may copy, modify, and redistribute it without restriction.

**Q: Will this code actually run on a modern computer?**

Not directly. The AGC is a 15-bit fixed-architecture machine with its own opcodes, registers, and core-rope memory layout. To run it you need an emulator. The [Virtual AGC](https://github.com/virtualagc/virtualagc) project provides `yaAGC` (the simulator) and `yaDSKY2` (the DSKY UI). With those, you can assemble `Luminary099/MAIN.agc` and execute it.

**Q: What's the difference between Comanche055 and Luminary099?**

Comanche055 ran on the Command Module Computer aboard *Columbia*; Luminary099 ran on the Lunar Module Guidance Computer aboard *Eagle*. They share an executive, interpreter, IMU services, and DSKY UI, but the application layer differs entirely — Comanche handles atmospheric reentry, CSM attitude, and trans-Earth/-Lunar trajectories; Luminary handles powered descent, lunar surface stay, ascent, and rendezvous.

**Q: Why are there so many translations of README.md?**

The repository has historically welcomed translation contributions, and the Apollo program has worldwide cultural significance. Each translation makes the source code more accessible to a non-English-reading audience. They are README/CONTRIBUTING translations only — the AGC source code itself remains in English (the comments are historical artifacts, not translatable content).

**Q: Is this the "real" Apollo 11 source code?**

Yes — these files are line-by-line transcriptions of the actual hardcopy printouts produced by the GAP assembler in 1969 and archived at the MIT Museum. The transcription is community-driven, so individual lines may contain digitisation typos still being corrected (see proof-reading issues in Section 5.6). For absolute fidelity, cross-check against the [scanned printouts](http://www.ibiblio.org/apollo/ScansForConversion/Luminary099/).

**Q: Was Margaret Hamilton involved with this code?**

Yes. Margaret H. Hamilton was the **Colossus Programming Leader** at MIT's Instrumentation Laboratory and signed off on the Comanche055 program on **28 March 1969**. The contract block in `Comanche055/CONTRACT_AND_APPROVALS.agc` records her approval signature alongside Daniel J. Lickly, Fred H. Martin, Norman E. Sears, Richard H. Battin, David G. Hoag, and Ralph R. Ragan.

**Q: What were the 1201 and 1202 alarms during the lunar landing?**

These are AGC restart codes (octal). 1201 = "executive overflow — no VAC areas"; 1202 = "executive overflow — no core sets". They were triggered by spurious rendezvous-radar interrupts overloading the executive. The restart logic in `RESTARTS_ROUTINE.agc` and `FRESH_START_AND_RESTART.agc` recovered the active mission program and continued the descent without losing data — a triumph of fault-tolerant design that allowed the landing to proceed.

**Q: How do I find the file that contains a specific verb or noun?**

Verbs ≥40 are dispatched from a fan-out table at the top of `EXTENDED_VERBS.agc`. Verbs <40 are dispatched in `PINBALL_GAME_BUTTONS_AND_LIGHTS.agc`. Noun definitions are in `PINBALL_NOUN_TABLES.agc`. To find a specific verb's implementation: `grep -rn "VERB69\|VB69" Luminary099/`.

**Q: Can I add my own changes that improve the code?**

The repository is a **historical archive**. Code-improvement PRs are not accepted — only proof-reading corrections that bring the transcription closer to the original scanned printouts. If you want to experiment with the AGC, fork the repo or work on the [Virtual AGC](https://github.com/virtualagc/virtualagc) project, which actively maintains running simulations.

**Q: Is the source archived anywhere besides GitHub?**

Yes, it is mirrored on [Software Heritage](https://archive.softwareheritage.org/browse/origin/https://github.com/chrislgarry/Apollo-11/), guaranteeing long-term preservation independent of GitHub's availability.

**Q: What does "Colossus 2A" mean?**

"Colossus" is the family name for the Command Module flight programs across multiple Apollo missions. "2A" is a specific revision in that family, of which **Comanche** is build series 055 (the version flown on Apollo 11). Equivalently, "Luminary" is the Lunar Module program family, and **Luminary 1A build 099** flew on Apollo 11.

**Q: Why is one file called `BURN_BABY_BURN--MASTER_IGNITION_ROUTINE.agc`?**

That is its real name in the original 1969 printout — the engineers had a sense of humour. It is the master ignition routine for the descent and ascent main engines. The double dash is preserved exactly as printed.

**Q: Why is the DSKY driver called `PINBALL_GAME_BUTTONS_AND_LIGHTS.agc`?**

The original NASA team treated the keypad and display lamps as a pinball-machine I/O surface — a charming 1969 metaphor that survived into the canonical filename. It does the keyboard scanning, display refresh, lamp logic, and verb/noun decoding.

**Q: Where can I learn more about how the AGC actually works?**

Three excellent starting points:

1. The [Virtual AGC project documentation](https://www.ibiblio.org/apollo/) — Ron Burkey's comprehensive site on AGC architecture, scans, and emulation.
2. [*Digital Apollo: Human and Machine in Spaceflight*](https://mitpress.mit.edu/9780262134972/) by David A. Mindell — the definitive engineering history.
3. [Don Eyles' *Sunburst and Luminary*](http://www.sunburstandluminary.com/) — first-person memoir by one of Luminary's principal authors.

**Q: How do I find the page number in the original printout for a given line of code?**

Each `.agc` file embeds page-number anchors as comments (`# Page 785`). Search backwards from the line of interest for the most recent `# Page` comment. Cross-reference to the scanned printout at the corresponding URL in `Comanche055/README.md` or `Luminary099/README.md`.

---

_Generated April 2026 from chrislgarry/Apollo-11 at 247dd7d. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._