diff --git a/README.md b/README.md
index 9629e9f..eaca382 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,10 @@ The port aims to be **easy to host**. It runs as one process with one SQLite dat
- Chartkick and Chart.js draw the oil and fuel charts.
- Authentication uses the Rails 8 built-in generator (sessions plus password reset).
+## User guide
+
+The [user guide](docs/guide/README.md) explains how to use the app, for pilots, owners, mechanics and admins. The same pages are shown in the app under **Help**.
+
## Quick start (development)
```bash
@@ -110,7 +114,7 @@ To back up or move a single aircraft with all its files, use **Access & Sharing
| Documents | Collections, multi-file documents with a page viewer, per-document share visibility, bulk upload, and expiration dates (registration, insurance…). |
| Electronic signatures | Logbook entries can be signed electronically along the lines of AC 120-78B chapter 2: the signer reviews the entry, picks their certificate, re-enters their password (or signs in again with SSO) and confirms a "Certified by" statement. The signature records who, which certificate, the statement, the time and a SHA-256 fingerprint of the entry, sealed by the server; the signer gets an email. Signed entries are locked: a correction is a new signed entry that supersedes the original. Owners can invite an outside mechanic to sign one entry with their own account. Disabled accounts can't sign; their past signatures stay. |
| Records integrity | Every change to maintenance records is kept (who, when, field by field) in a hash chain per aircraft (Activity → Record history). Nightly: a verified SQLite backup in `storage/backups` (how many are kept: Admin → Settings), then a check of the history chains and every signature; admins are emailed on a problem (Admin → About). Software versions are recorded. A records package (Access & Sharing) bundles every entry as a PDF with signatures, a signature register, the history, the status report and the `.sam.zip` for the FAA or a buyer. Scans of paper logbooks can be marked as legacy records, with an "electronic records since" date per aircraft. |
-| Recordkeeping procedures and audits | Admin → Recordkeeping Procedures generates the procedures document AC 120-78B asks for (who is responsible, who may sign, signing, corrections, backups, access, audits, transfer, legacy records) from the system setup plus a few details you fill in; adopt it as numbered, unchangeable revisions, included in the records package. Admin → Records Audits is a periodic QC checklist (app checks plus a restore test, a sample of entries against source documents and a user review); admins get the due date in the weekly reminder. Users' instructions are at `/help/records`, linked from the logbook and the signing page. |
+| Recordkeeping procedures and audits | Admin → Recordkeeping Procedures generates the procedures document AC 120-78B asks for (who is responsible, who may sign, signing, corrections, backups, access, audits, transfer, legacy records) from the system setup plus a few details you fill in; adopt it as numbered, unchangeable revisions, included in the records package. Admin → Records Audits is a periodic QC checklist (app checks plus a restore test, a sample of entries against source documents and a user review); admins get the due date in the weekly reminder. The users' instructions are the guide's [Electronic records and signing](docs/guide/records.md) page. |
| Major repairs and alterations | Form 337, STC, and ICA tracking; an STC's ICA can become a tracked recurring inspection. |
| Weight & balance | History of empty weight and CG (linked to the alteration that changed them) and a loading calculator: takeoff and landing weight and CG against max gross and the CG envelope. |
| Status report | A printable maintenance status (91.417(a)(2)): total times, life-limited parts, time since overhaul, inspections, ADs with method and revision, major alterations, open discrepancies. Also on maintenance share links. |
diff --git a/app/assets/tailwind/application.css b/app/assets/tailwind/application.css
index 9c3c20f..434b386 100644
--- a/app/assets/tailwind/application.css
+++ b/app/assets/tailwind/application.css
@@ -130,6 +130,10 @@
.markdown table { display: block; max-width: 100%; overflow-x: auto; border-collapse: collapse; font-size: 0.85em; }
.markdown th, .markdown td { border: 1px solid var(--color-slate-200); padding: 0.25rem 0.5rem; text-align: left; }
.markdown th { background: var(--color-slate-50); font-weight: 600; }
+ .markdown.guide { line-height: 1.6; }
+ .markdown.guide h1 { font-size: 1.5rem; font-weight: 700; }
+ .markdown.guide h2 { font-size: 1.15rem; margin-top: 1.25em; }
+ .markdown.guide h3 { margin-top: 1em; }
}
/* ---- Phones ---------------------------------------------------------- */
diff --git a/app/controllers/help_controller.rb b/app/controllers/help_controller.rb
index 13db097..67fce77 100644
--- a/app/controllers/help_controller.rb
+++ b/app/controllers/help_controller.rb
@@ -1,4 +1,8 @@
-# User instructions for electronic records and signatures (AC 120-78B 2.2.12, 3.2.9).
+# The user guide (docs/guide), including the instructions for electronic
+# records and signatures (AC 120-78B 2.2.12, 3.2.9).
class HelpController < ApplicationController
- def records; end
+ def show
+ @page = HelpGuide.find(params[:page] || "README") or raise ActionController::RoutingError, "Not found"
+ @pages = HelpGuide.pages
+ end
end
diff --git a/app/helpers/help_helper.rb b/app/helpers/help_helper.rb
new file mode 100644
index 0000000..a67b7b9
--- /dev/null
+++ b/app/helpers/help_helper.rb
@@ -0,0 +1,10 @@
+module HelpHelper
+ def help_page_url_for(slug, anchor = nil)
+ slug == "README" ? help_path(anchor: anchor) : help_page_path(slug, anchor: anchor)
+ end
+
+ def guide_html(page, links: true, title: true)
+ html = HelpGuide.html(page, title: title, link: (links ? method(:help_page_url_for) : nil))
+ tag.div(html.html_safe, class: "markdown guide") # rubocop:disable Rails/OutputSafety -- sanitized in HelpGuide
+ end
+end
diff --git a/app/models/help_guide.rb b/app/models/help_guide.rb
new file mode 100644
index 0000000..31ef44f
--- /dev/null
+++ b/app/models/help_guide.rb
@@ -0,0 +1,39 @@
+# The user guide: Markdown files in docs/guide (readable on GitHub too),
+# shown in the app under /help. Only the pages listed here can be opened.
+class HelpGuide
+ DIR = Rails.root.join("docs/guide")
+ ORDER = %w[README getting-started profile aircraft flights squawks oil-and-fuel components logbook records
+ inspections ads documents major-records sharing administration].freeze
+ OPTIONS = {
+ parse: { smart: true },
+ render: { hardbreaks: false, unsafe: false },
+ extension: { strikethrough: true, tagfilter: true, table: true, autolink: true, header_ids: "" }
+ }.freeze
+ TAGS = %w[p br strong em del a ul ol li blockquote code pre h1 h2 h3 h4 hr table thead tbody tr th td].freeze
+ ATTRIBUTES = %w[href id align].freeze
+
+ Page = Data.define(:slug, :title, :markdown)
+
+ def self.pages = ORDER.filter_map { find(_1) }
+
+ def self.find(slug)
+ return unless ORDER.include?(slug.to_s)
+ path = DIR.join("#{slug}.md")
+ return unless path.file?
+ markdown = path.read
+ Page.new(slug: slug.to_s, title: markdown[/\A# (.+)$/, 1] || slug.to_s.titleize, markdown: markdown)
+ end
+
+ # Sanitized HTML. Links to other guide pages ("records.md#mistakes") go
+ # through `link` (slug, anchor) -> URL, or become plain text when nil.
+ def self.html(page, link:, title: true)
+ source = title ? page.markdown : page.markdown.sub(/\A# .+\n+/, "")
+ html = Commonmarker.to_html(source, options: OPTIONS, plugins: { syntax_highlighter: nil })
+ html = Rails::HTML5::SafeListSanitizer.new.sanitize(html, tags: TAGS, attributes: ATTRIBUTES)
+ html.gsub(%r{(.*?)}m) do
+ slug, anchor, text = $1, $2, $3
+ next text unless link && ORDER.include?(slug)
+ %(#{text})
+ end
+ end
+end
diff --git a/app/views/admin/procedures/_document.html.erb b/app/views/admin/procedures/_document.html.erb
index 0e87a38..6b95678 100644
--- a/app/views/admin/procedures/_document.html.erb
+++ b/app/views/admin/procedures/_document.html.erb
@@ -97,7 +97,7 @@
13. User instructions and training
Every user who keeps or signs records reads these instructions (also in the system under “How electronic records work”) before signing (2.2.12, 3.2.9).
diff --git a/app/views/help/_records_content.html.erb b/app/views/help/_records_content.html.erb
deleted file mode 100644
index 074a0ac..0000000
--- a/app/views/help/_records_content.html.erb
+++ /dev/null
@@ -1,21 +0,0 @@
-<%# User instructions for electronic records (also an appendix of the procedures document). %>
-
-
Writing an entry
-
On the aircraft's Logbook tab, choose + New Entry. Give the date, the logbook (aircraft, engine, propeller), the airframe total time, and what was done; for an engine or propeller entry pick the component (its times fill in) and tick any sub-components. A template can start the wording. An entry isn't a signed record until it's signed.
-
Signing
-
-
Add your certificate (kind and number) once, on your profile.
-
Open the entry and choose Sign. Read the entry as shown: your signature covers exactly that.
-
Pick the certificate you're signing with. The statement you'll certify is shown with it (return to service, or the inspection statement).
-
Re-enter your password, or sign in again with single sign-on, tick the confirmation and choose Sign entry. You'll see a confirmation and get an email.
-
-
Never share your password or let someone else sign while you're signed in: a signature is yours alone. If you think someone has, tell the administrator straight away.
-
Mistakes
-
A signed entry can't be edited or deleted. Open it and choose Correct this entry: a new entry starts from the original; fix it, save, and sign it. The original stays, marked “Superseded by a correction”.
-
Someone else did the work
-
The owner can choose Ask someone to sign on the entry: the mechanic gets a one-time email link, signs in or creates their own account, adds their certificate and signs. If they prefer paper, print the entry (Print for logbook), have it signed in ink, and keep the paper with the logbooks (scan it into Documents).
-
Checking a record
-
A signed entry shows who certified it, with which certificate, when (UTC), what they certified, and its status. Valid means nothing has changed since signing. The fingerprint (a SHA-256 of the entry) is printed on paper copies so a copy can be matched to the record. Every change to any record is kept under Activity → Record history.
-
If the system is down
-
Make the entry on paper and sign it in ink. When the system is back, add the entry and scan the signed paper into Documents; the paper itself stays with the logbooks and remains the signed record for that entry.
<% end %>
+ <%= link_to "Help", help_path, class: "hover:text-sky-300" %>
<%= link_to current_user.display_name, edit_profile_path, class: "text-white/70 hover:text-sky-300 hidden sm:inline" %>
<%= render "shared/theme_toggle" %>
<%= button_to "Sign out", session_path, method: :delete, class: "rounded bg-white/10 px-2 py-1 hover:bg-white/20" %>
diff --git a/config/routes.rb b/config/routes.rb
index da80ec9..bd94163 100644
--- a/config/routes.rb
+++ b/config/routes.rb
@@ -108,7 +108,9 @@ Rails.application.routes.draw do
end
get "airports/search", to: "airports#search", as: :airport_search
- get "help/records", to: "help#records", as: :records_help
+ get "help", to: "help#show", as: :help
+ get "help/records", to: "help#show", defaults: { page: "records" }, as: :records_help
+ get "help/:page", to: "help#show", as: :help_page, constraints: { page: /[a-z-]+/ }
# Public read-only share links (no login).
# Invited signers (outside mechanics) sign one entry.
diff --git a/docs/guide/README.md b/docs/guide/README.md
new file mode 100644
index 0000000..790c6f9
--- /dev/null
+++ b/docs/guide/README.md
@@ -0,0 +1,31 @@
+# User guide
+
+Simple Aircraft Manager keeps the records and status of a small fleet: hours, squawks, components, the maintenance logbook, inspections, ADs, documents, oil and fuel, weight and balance. It works out whether each aircraft is airworthy from those records. This guide explains how to use it, for everyone who flies, maintains or administers the aircraft.
+
+The same pages are in the app under **Help** in the menu.
+
+## Everyone
+
+- [Getting started](getting-started.md): signing in, roles, finding your way around, phones
+- [Your profile](profile.md): password, certificates, single sign-on, reminders, AirTrail
+- [Aircraft and airworthiness](aircraft.md): the fleet, an aircraft's overview, what the status means
+- [Flights and hours](flights.md): logging flights, updating meters, imports, engine data
+- [Squawks](squawks.md): reporting, deferring and resolving problems
+- [Oil, fuel and oil analysis](oil-and-fuel.md)
+
+## Owners and mechanics
+
+- [Components](components.md): parts, limits, TBO, service and replacement
+- [The logbook](logbook.md): writing entries, templates, scanned logbooks, printing
+- [Electronic records and signing](records.md): how signing, corrections and the record history work
+- [Inspections](inspections.md)
+- [Airworthiness directives](ads.md)
+- [Documents](documents.md)
+- [Major repairs, alterations and weight & balance](major-records.md)
+- [Access, sharing and transfer](sharing.md): people, share links, the records package, moving an aircraft
+
+## Administrators
+
+- [Administration](administration.md): users, settings, templates, backups, recordkeeping procedures and audits
+
+Installing and hosting the app is covered in the project's main README.
diff --git a/docs/guide/administration.md b/docs/guide/administration.md
new file mode 100644
index 0000000..acf2c69
--- /dev/null
+++ b/docs/guide/administration.md
@@ -0,0 +1,59 @@
+# Administration
+
+Admins see the **Admin** menu (on a phone, under ☰). Admins can see and edit every aircraft.
+
+## Users
+
+**Users** lists every account.
+
+- **+ New User**: name, email and a starting password. Tick **Administrator** to make them an admin. Then add them to aircraft from each aircraft's **Access & Sharing** tab (or they add their own aircraft).
+- **Edit** to change details or reset a password when email isn't set up.
+- **Disable** someone who no longer needs access: they're signed out and can't sign in or sign entries, and their past signatures stay. **Enable** reverses it. Users who have signed entries can't be deleted, only disabled.
+
+With single sign-on, accounts can be created automatically at first sign-in, and admin rights can follow a group at the provider (see the main README).
+
+## Component Types, Airports, Logbook Templates
+
+- **Component Types**: the list of types used for components (owners can also add new types while adding a component).
+- **Airports**: airport data from OurAirports, used for From/To autocomplete and AirTrail. It downloads by itself when the app first starts; **Update from OurAirports** refreshes it. Add private strips here; they're never overwritten.
+- **Logbook Templates**: the wording offered when writing an entry. Use `__` for blanks. **Restore built-in templates** adds back any deleted built-in ones.
+
+## Settings
+
+- **Uploads**: the largest file anyone can upload. A proxy in front of the app may have its own smaller limit.
+- **Backups**: how many nightly database copies to keep.
+
+## About
+
+**About** shows the running version, features and storage, and has tools:
+
+- **Send test email** and **Send me this week's reminder** check that email works.
+- **Records integrity**: the last nightly backup and records check. **Back up and check now** runs both straight away.
+- **Records**: the current recordkeeping procedures revision, the last audit and when the next is due.
+- **Software versions**: when each version of the app was first run.
+
+## Backups
+
+Every night at 3:30 the app makes a verified copy of the database in `storage/backups`, then checks the record history and every signature. Admins are emailed if anything fails.
+
+Those copies sit on the same server. **Back up the whole storage volume somewhere else too** (another machine or a cloud service), and test restoring it now and then. That's part of every records audit.
+
+## Recordkeeping procedures
+
+If the app replaces the paper logbooks, AC 120-78B asks for a written procedures document. **Recordkeeping Procedures** generates one from the app's setup:
+
+1. Fill in the **details** the app can't know: the owner/operator, the person responsible for the records, how the app is hosted, how it's backed up off-site, and how often to audit and how many entries to sample.
+2. **Preview the draft** and read it through.
+3. **Adopt** it as a revision, with a note of what changed. Adopted revisions can't be changed; print one or save it as a PDF with the records.
+
+The document covers responsible personnel, users and roles, the signing process, system controls, audits, making records available to the FAA, transfer, continuity and changes, with these [user instructions](records.md) as an appendix. Adopt a new revision whenever users, hosting or procedures change. The current revision goes into each aircraft's records package.
+
+## Records audits
+
+**Records Audits** is the periodic quality check the procedures promise. **Start an audit**:
+
+- The app shows its own checks: the latest integrity check and backup, the procedures, signatures, expired certificates, and software changes since the last audit.
+- You confirm the rest: that you restored the off-site backup somewhere separate and opened it; that a random sample of entries matches their work orders or receipts; that the users and roles are right (disable anyone who no longer needs access); and that the paper logbooks are kept.
+- Add a note for each item and overall, then **Record audit**. Audits can't be changed afterwards.
+
+The next one is due after the interval set in the procedures. It shows on About, and admins are reminded in the weekly email.
diff --git a/docs/guide/ads.md b/docs/guide/ads.md
new file mode 100644
index 0000000..0327867
--- /dev/null
+++ b/docs/guide/ads.md
@@ -0,0 +1,19 @@
+# Airworthiness directives
+
+The **ADs** tab lists the ADs and bulletins that apply to the aircraft or its components, their compliance status, and the compliance history.
+
+## Adding ADs
+
+- **+ New AD**: the number, type (AD, SAIB, SB, alert, other), standard or conditional, what it requires, whether it recurs (every so many hours and/or months; due at the end of the month) and a link to the AD. A conditional AD only applies when its trigger happens (“on prop strike”) and doesn't affect airworthiness. Non-mandatory bulletins can be tracked too.
+- **Link existing**: ADs are shared between aircraft; link one already entered for another aircraft.
+- **Import from FAA DRS**: export the ADs for the aircraft, engine and propeller from the FAA's Dynamic Regulatory System, preferably as `.xlsx` so each AD keeps its DRS link, and upload it. The preview suggests **Track**, **Not applicable** or **Skip** for each AD and flags superseded ADs, model mismatches, appliance and STC-only ADs, and recurring actions. Nothing is duplicated.
+
+## Newly published ADs
+
+The app searches the Federal Register weekly for new ADs mentioning the aircraft, engine and propeller models (or the terms you set). **Check now** runs it straight away. For each match, **Track** it or **Dismiss** it. Matches are only *possibly* applicable: check the AD's applicability and serial number ranges first.
+
+## Recording compliance
+
+**Comply** records the date, aircraft hours, the component, the logbook entry, the method (inspection, terminating action, AMOC) and the AD revision complied with, with details of what was done. **N/A** records that an AD doesn't apply, and why (for example, serial number outside the affected range). Recurring ADs then show when they're next due.
+
+Make the logbook entry for the work as well; the status report lists each AD with its method and revision (91.417(a)(2)(v)).
diff --git a/docs/guide/aircraft.md b/docs/guide/aircraft.md
new file mode 100644
index 0000000..9bfe9f8
--- /dev/null
+++ b/docs/guide/aircraft.md
@@ -0,0 +1,41 @@
+# Aircraft and airworthiness
+
+## The fleet
+
+**Fleet** shows every aircraft you have access to, with its airworthiness and its most pressing issues. **+ Add Aircraft** creates one (you become its owner). **Import** loads an aircraft from a `.sam.zip` archive (see [Access, sharing and transfer](sharing.md)).
+
+## An aircraft's overview
+
+The **Overview** tab shows:
+
+- **Airworthiness**: the overall status and each reason for it.
+- **Active squawks**, **Consumption** (oil and fuel rates), **Notes** and **Recent activity**.
+- **Update Hours**: enter the current meter readings (see [Flights and hours](flights.md)).
+- **Details** and the **Status report** link.
+
+## What the airworthiness status means
+
+The app works out a status from the records:
+
+- **Grounded**: something makes the aircraft unairworthy: an overdue AD, a squawk marked *Ground Aircraft*, an overdue inspection that grounds, a replacement-critical part overdue or expired, or an expired registration.
+- **Limited**: airworthy with a limitation, such as *VFR only* when the IFR (91.411) check is overdue, or no transponder use when the 91.413 check is.
+- **Due soon**: something comes due within 10 hours or 30 days.
+- **Current**: nothing due.
+
+It's only as good as the records entered, and the pilot in command still decides whether the aircraft is airworthy (14 CFR 91.7).
+
+## Editing the aircraft
+
+**Edit** (owners) on the overview changes:
+
+- Tail number, make, model, serial number, status (Available, In Maintenance, Grounded, Unavailable), ICAO type (used for AirTrail), description and picture.
+- **Current tach / hobbs**, and **offsets** subtracted for maintenance math after a meter is replaced.
+- Which meter is the maintenance clock (tach or Hobbs).
+- **Electronic records since**: the date this app became the maintenance record. Earlier records stay in the paper logbooks.
+- **Enforce airworthiness**: blocks flight logs and hours updates while the aircraft is grounded.
+
+The **Danger zone** deletes the aircraft and everything in it. Export it first if you might need it again.
+
+## Status report
+
+**Status report** is a printable summary of the aircraft's maintenance status (14 CFR 91.417(a)(2)): total time, life-limited parts, time since overhaul, inspections, AD status with method and revision, major alterations and open discrepancies. Print it or save it as a PDF from the browser.
diff --git a/docs/guide/components.md b/docs/guide/components.md
new file mode 100644
index 0000000..d5e5ba2
--- /dev/null
+++ b/docs/guide/components.md
@@ -0,0 +1,25 @@
+# Components
+
+The **Components** tab is a tree of the aircraft's parts: engine, propeller, magnetos, filters, ELT battery and so on, each with its own time and limits. Owners manage it.
+
+## Adding a component
+
+**+ Add Component**, or **+ Sub-component** on a component's page to put one under it (an oil filter under the engine, say). For each:
+
+- **Type** (pick one, or type a new one), manufacturer, model, serial number, install location and status.
+- **Time**: date in service, total time, last overhaul or service, hours since, and for engines and propellers the overhaul kind (printed in logbook entries as SMOH, SFOH or SNEW).
+- **Limits**:
+ - **Replace every** hours and/or days; **Replacement critical** makes overdue replacement ground the aircraft (oil, filters, ELT battery…).
+ - **Expires on**: a date marked on the part, such as an ELT battery's.
+ - **TBO** hours and/or days. Under Part 91 TBO is usually a recommendation; tick **Treat TBO as a hard limit** only when an AD or the airworthiness limitations make it one, or **On condition** to show it without warnings.
+ - **Inspect every** hours and/or days, optionally critical.
+
+Logged hours are added to every component that's in service.
+
+## Service and replacement
+
+On a component's page, **Service / Replace → Record Service** resets hours since overhaul or service to 0 and sets the service date to today, for example after an oil change. Tick *Part was physically replaced* to reset its total time and in-service date too.
+
+Record the work in the [logbook](logbook.md) as well: the component reset tracks time, the logbook entry is the record.
+
+**Show disposed** lists parts that have been removed and disposed of.
diff --git a/docs/guide/documents.md b/docs/guide/documents.md
new file mode 100644
index 0000000..5016f34
--- /dev/null
+++ b/docs/guide/documents.md
@@ -0,0 +1,19 @@
+# Documents
+
+The **Documents** tab keeps scans and files: registration, airworthiness certificate, insurance, logbook scans, receipts, 337s, reports.
+
+- **+ Upload Document**: a name, type, collection, description, and one or more files (images, PDFs or text). Each file is a page in the viewer.
+- **Bulk upload**: many files at once. Each becomes its own document named after the file; files with the same name are combined, in order, as pages of one document.
+- **+ Collection** groups documents (for example *Engine logbook* or *Annual 2026*).
+
+## Expiry
+
+Give a registration, insurance policy or similar an expiration date and it shows on the airworthiness status as it approaches. An expired registration grounds the aircraft (91.203(a)(2)).
+
+## Share-link visibility
+
+Each collection or document is **Private**, visible on **all share links**, or **maintenance only** share links. See [Access, sharing and transfer](sharing.md).
+
+## Legacy records
+
+Tick **Legacy record** for scans of the paper logbooks and records from before the aircraft's *electronic records since* date. The paper originals remain the record for that period and must be kept.
diff --git a/docs/guide/flights.md b/docs/guide/flights.md
new file mode 100644
index 0000000..559ab06
--- /dev/null
+++ b/docs/guide/flights.md
@@ -0,0 +1,26 @@
+# Flights and hours
+
+Every hour flown is added to the aircraft and to each installed component, which is what moves inspections, ADs, TBOs and replacement times toward due.
+
+## Log a flight
+
+**Log Flight** (top of every aircraft page) records:
+
+- The date, and **tach out / in** and **Hobbs out / in**, or just the durations.
+- Oil and fuel added, the level after and the product. These feed the oil and fuel trends.
+- The route (From/To airports autocomplete) and notes.
+- Optionally a **track log** (GPX, KML or CSV) and **engine monitor data** (CGR-30P / CGR-30C `.csv`), which you can chart on the flight's page.
+
+## Update hours
+
+When you don't log each flight, use **Update Hours** on the overview: enter the current meter readings and the difference is applied to every installed component. A reading lower than the current one is treated as a correction.
+
+If **Enforce airworthiness** is on, neither works while the aircraft is grounded.
+
+## The Flights tab
+
+The **Flights** tab lists flights with totals and hours by month. From there:
+
+- **Import from spreadsheet** (owners): historical flights from `.xlsx` or `.csv` (Date, From, To, Tach, Hobbs, Oil Added, Fuel Added). A preview flags problems such as a tach going backwards and skips rows already imported. It only adds history: component hours don't change unless you choose to advance the meters.
+- **Export for AirTrail**: a file to import into AirTrail. For automatic syncing, see [Your profile](profile.md).
+- **Standardize airport codes**: fix codes that don't match a known airport (often a typo), or add a private strip.
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
new file mode 100644
index 0000000..2a2c7b2
--- /dev/null
+++ b/docs/guide/getting-started.md
@@ -0,0 +1,41 @@
+# Getting started
+
+## Signing in
+
+Depending on how the app is set up, you can sign in with:
+
+- **Email and password.** Your administrator creates your account. Use **Forgot password?** to reset it if email is set up; otherwise ask the administrator.
+- **Email me a sign-in link.** Enter your email and use the link sent to you. It works once, for a short time.
+- **Single sign-on** (for example *Sign in with Authentik*), if your organization uses it.
+
+The very first visit to a new installation asks for the administrator account instead.
+
+## Roles
+
+What you can do depends on your role on each aircraft:
+
+| | Pilot | Owner | Admin |
+|---|:-:|:-:|:-:|
+| See everything on the aircraft | ✓ | ✓ | ✓ |
+| Log flights, update hours, report squawks, add notes, oil and fuel | ✓ | ✓ | ✓ |
+| Defer a squawk as inoperative | ✓ | ✓ | ✓ |
+| Sign logbook entries (with your own certificate) | ✓ | ✓ | ✓ |
+| Edit squawks and notes, resolve squawks | | ✓ | ✓ |
+| Components, logbook, inspections, ADs, documents, major records, W&B | | ✓ | ✓ |
+| Edit the aircraft, manage people and share links | | ✓ | ✓ |
+| Users, settings, procedures and audits for the whole app | | | ✓ |
+
+Anyone can add an aircraft and becomes its owner. You only see aircraft you have a role on; admins see all of them.
+
+## Finding your way around
+
+- **Fleet** (top left) lists your aircraft with their airworthiness.
+- Each aircraft has tabs: **Overview, Components, Squawks, Flights, Oil & Fuel, Oil Analysis, Logbook, Inspections, ADs, Documents, Major Records, W&B, Notes, Activity**, and for owners **Access & Sharing**.
+- **Log Flight** and **Report Squawk** are at the top of every aircraft page.
+- Your name (or ☰ on a phone) leads to your **Profile**, this **Help**, and for admins the **Admin** pages.
+
+## On a phone
+
+The app works on phones. The tabs collapse into a **Section** menu, and wide tables scroll sideways. You can install it like an app: in Safari use **Share → Add to Home Screen**, in Chrome **Install app**.
+
+The sun/moon button switches between light and dark themes.
diff --git a/docs/guide/inspections.md b/docs/guide/inspections.md
new file mode 100644
index 0000000..dcef636
--- /dev/null
+++ b/docs/guide/inspections.md
@@ -0,0 +1,18 @@
+# Inspections
+
+The **Inspections** tab shows each required inspection, when it was last done and when it's next due.
+
+## Setting up
+
+**Standard inspections** adds the recurring inspections and checks Part 91 calls for (annual, 100-hour, pitot-static and altimeter, transponder, ELT…). Pick the ones that apply to how the aircraft is flown; each comes with its interval and what being overdue means, and you can change them afterwards.
+
+**+ Inspection Type** adds your own, for example a recurring inspection from an STC's instructions for continued airworthiness. Each type has:
+
+- **Recurring** every so many hours, calendar months (due at the end of the month) and/or days.
+- What overdue means: **grounds the aircraft**, **no IFR flight** (91.411), **transponder can't be used** (91.413), or **advisory only**.
+- **Overrun allowance**: for the 100-hour, 10 hours. Done late within it, the next one counts from when it was due (91.409(b)).
+- **Also counts as**: an annual also counts as the 100-hour.
+
+## Recording an inspection
+
+**Record** next to an inspection logs the date and hours it was done, optionally linking the logbook entry. The [logbook](logbook.md) entry is the signed record (14 CFR 43.11); write it too.
diff --git a/docs/guide/logbook.md b/docs/guide/logbook.md
new file mode 100644
index 0000000..1bfb37b
--- /dev/null
+++ b/docs/guide/logbook.md
@@ -0,0 +1,42 @@
+# The logbook
+
+The **Logbook** tab holds the maintenance record entries. Owners write and edit them; anyone with a certificate can sign them (see [Electronic records and signing](records.md)).
+
+## Writing an entry
+
+**+ New Entry**:
+
+1. Choose a **Template** to start the wording if one fits, and fill in its blanks (`__`). The built-in ones are for a pilot doing preventive maintenance on an aircraft they own or operate (14 CFR 43.3(g)); admins can add their own.
+2. Fill in the date, the **logbook** (aircraft, engine, propeller or other), the **entry type** (usually maintenance or inspection) and the **airframe total time**.
+3. For an engine or propeller entry, pick the component: its total time and time since overhaul at the entry fill in from the airframe time. Tick any **sub-components** included in the work (an oil filter on the engine) to record their times as well.
+4. Write the **entry text**: what was done, with reference to the data used.
+5. The sign-off fields (who, certificate kind and number, location) are filled in when the entry is signed electronically. Fill them in yourself for an entry copied from a paper logbook.
+6. For an inspection, record the **inspection result** (approved for return to service, or a list of discrepancies given to the owner).
+
+The entry flags anything 14 CFR 43.9 or 43.11 requires that's missing.
+
+An entry can link to the page of a scanned document it came from.
+
+Unsigned entries can be edited and deleted. Signed entries are locked; see [corrections](records.md#mistakes).
+
+## Searching
+
+Search the text, filter by logbook, and show only unverified transcribed entries.
+
+## Importing scanned logbooks
+
+**Import scans** uploads photos or PDFs of paper logbook pages as a document, in file-name order (name them `page-001`, `page-002`…). If the administrator has set an Anthropic API key, Claude reads them and adds each entry to the logbook.
+
+Transcribed entries are marked **unverified** until someone compares each with the scan and chooses **Matches the scan: mark verified**; the app then moves to the next one. Fix any mistake with **Edit** first.
+
+Mark the scans as **legacy records** (see [Documents](documents.md)): the paper logbooks stay the record for that period, and must be kept.
+
+## Printing entries for the paper logbook
+
+Tick entries and choose **Print selected**, or **Print for logbook** on one entry. Choose Avery 5163/8163 or 5164/8164 labels, or half-letter or letter pages (letter also fits full-sheet labels); on a part-used label sheet, pick the first free label. Print at 100% (“Actual size”), not “Fit to page”, and try a plain sheet first.
+
+Each printed entry has a line to sign by hand: a printed entry isn't a record until it's signed. An entry signed electronically prints with its electronic signature and fingerprint instead.
+
+## Templates
+
+Admins change the template list under **Admin → Logbook Templates** (also linked from the new-entry form). See [Administration](administration.md).
diff --git a/docs/guide/major-records.md b/docs/guide/major-records.md
new file mode 100644
index 0000000..d4c9f86
--- /dev/null
+++ b/docs/guide/major-records.md
@@ -0,0 +1,17 @@
+# Major repairs, alterations and weight & balance
+
+## Major records
+
+The **Major Records** tab lists major repairs and alterations: **+ Repair** or **+ Alteration** records the date, aircraft hours, what was done and by whom, the component, the Form 337 document, the logbook entry, and for an STC its number, holder and document.
+
+If it includes **instructions for continued airworthiness**, tick it and use **Add the ICA's recurring inspection** to track it as an [inspection](inspections.md). If it changed the empty weight or CG, **Record the new W&B**.
+
+## Weight & balance
+
+The **W&B** tab keeps the history of empty weight and CG.
+
+- **+ New W&B**: date, reason, empty weight, empty CG (arm aft of the datum), max gross weight, the alteration that caused it and the W&B report document. The newest record is the current one.
+- **Loading setup**: from the POH, the stations (seats, baggage, fuel tanks) with their arms and maximums, the fuel weight per gallon, and the corners of the CG envelope.
+- **Loading calculator**: enter people, baggage and fuel to see takeoff and landing weight and CG against max gross and the envelope.
+
+The calculator is a planning aid from the figures entered. Check against the POH and the aircraft's current W&B report.
diff --git a/docs/guide/oil-and-fuel.md b/docs/guide/oil-and-fuel.md
new file mode 100644
index 0000000..4ef8c32
--- /dev/null
+++ b/docs/guide/oil-and-fuel.md
@@ -0,0 +1,16 @@
+# Oil, fuel and oil analysis
+
+## Oil & Fuel
+
+Oil and fuel added when logging a flight are recorded automatically. The **Oil & Fuel** tab also takes records on their own (**+ Add Oil** / **+ Add Fuel**): quantity added, level after, product and tach time.
+
+It charts consumption and shows averages over the last 20 intervals, ignoring outliers. Tick **Exclude from averages** for an oil change, so the oil added isn't counted as consumption.
+
+## Oil analysis
+
+The **Oil Analysis** tab tracks lab results and charts wear metals over time.
+
+- **Import report**: upload an AvLab or Blackstone PDF. Every sample on it, including earlier ones, is added unless it's already there.
+- **+ Add Oil Analysis**: enter results by hand.
+
+Look for a steady trend rather than a single reading. Lead is left off the chart: it comes from 100LL and reads in the thousands.
diff --git a/docs/guide/profile.md b/docs/guide/profile.md
new file mode 100644
index 0000000..1df668d
--- /dev/null
+++ b/docs/guide/profile.md
@@ -0,0 +1,25 @@
+# Your profile
+
+Open your name in the top bar (☰ → **Profile** on a phone).
+
+## Details and password
+
+Change your name, email and password. Leave the password blank to keep the current one.
+
+**Weekly maintenance reminders**: on Mondays the app emails owners about anything overdue or coming due on their aircraft, and certificates about to expire. Untick it to stop them. (Emails need the administrator to have set up email.)
+
+## Certificates
+
+Add each certificate you sign maintenance records with: its kind (A&P, IA, airframe, powerplant, repairman, repair station, pilot…), its number, and for an IA, its expiry. You need one to sign a logbook entry, and the entry records which one you used. An IA expires on March 31 of each odd-numbered year unless renewed; you're reminded 60 days ahead.
+
+## Single sign-on
+
+If the app offers single sign-on, **Link** your account to it here so you can sign in with it, or **Unlink** it.
+
+## Sessions
+
+**Sign out everywhere else** ends your sessions on other devices, for example after using a shared computer or losing a phone.
+
+## Integrations: AirTrail
+
+**AirTrail sync** pushes the flights you log to your AirTrail flight map, with their GPS tracks. In AirTrail, create an API key (Settings → Security) with the scopes shown, then paste your AirTrail address and key here. A full sync first links flights already in AirTrail, so nothing is duplicated. If an airport code can't be matched, enter the code AirTrail uses for it.
diff --git a/docs/guide/records.md b/docs/guide/records.md
new file mode 100644
index 0000000..de8ffa9
--- /dev/null
+++ b/docs/guide/records.md
@@ -0,0 +1,42 @@
+# Electronic records and signing
+
+These are the instructions for everyone who keeps or signs maintenance records here. They're part of the aircraft's recordkeeping procedures (FAA Advisory Circular 120-78B), so read them before signing your first entry.
+
+## Writing an entry
+
+On the aircraft's **Logbook** tab, choose **+ New Entry** (owners). Give the date, the logbook (aircraft, engine, propeller), the airframe total time and what was done. For an engine or propeller entry, pick the component (its times fill in) and tick any sub-components. A template can start the wording. An entry isn't a signed record until it's signed. See [The logbook](logbook.md).
+
+## Signing
+
+1. Add your certificate (kind and number) once, on your [profile](profile.md).
+2. Open the entry and choose **Sign**. Read the entry as shown: your signature covers exactly that.
+3. Pick the certificate you're signing with. The statement you'll certify is shown with it (return to service, or the inspection statement).
+4. Re-enter your password, or sign in again with single sign-on, tick the confirmation and choose **Sign entry**. You'll see a confirmation and get an email.
+
+Never share your password or let someone else sign while you're signed in: a signature is yours alone. If you think someone has, tell the administrator straight away.
+
+## Mistakes
+
+A signed entry can't be edited or deleted. Open it and choose **Correct this entry** (owners): a new entry starts from the original. Fix it, save it and sign it. The original stays, marked “Superseded by a correction”, with a link to the correction.
+
+## Someone else did the work
+
+The owner can choose **Ask someone to sign** on the entry. The mechanic gets a one-time email link (valid for 14 days), signs in or creates their own account, adds their certificate and signs.
+
+If they prefer paper, print the entry (**Print for logbook**), have it signed in ink, and keep the paper with the logbooks (scan it into Documents).
+
+## Checking a record
+
+A signed entry shows who certified it, with which certificate, when (UTC), what they certified, and its status:
+
+- **Valid**: nothing has changed since signing.
+- **Superseded**: a signed correction replaces it.
+- **Altered**: the entry no longer matches what was signed. Tell the administrator.
+
+The fingerprint (a SHA-256 of the entry) is printed on paper copies so a copy can be matched to the record.
+
+Every change to any record is kept, with who made it and when, under **Activity → Record history** and in each entry's **Change history**. The history can't be edited, and it's checked every night along with every signature.
+
+## If the system is down
+
+Make the entry on paper and sign it in ink. When the system is back, add the entry and scan the signed paper into Documents. The paper stays with the logbooks and remains the signed record for that entry.
diff --git a/docs/guide/sharing.md b/docs/guide/sharing.md
new file mode 100644
index 0000000..d7184e2
--- /dev/null
+++ b/docs/guide/sharing.md
@@ -0,0 +1,28 @@
+# Access, sharing and transfer
+
+The **Access & Sharing** tab is for the aircraft's owners.
+
+## People
+
+Add people by email as **owner** or **pilot** (they need an account; ask the administrator). Change or remove their role at any time. See the roles table in [Getting started](getting-started.md).
+
+## Share links
+
+**Create Share Link** gives a read-only link that needs no account, for a mechanic, partner, buyer or insurer:
+
+- **Current Status**: airworthiness, open squawks, components, inspection and AD status, consumption, notes and shared documents.
+- **Maintenance Detail**: also the logbook, inspection and AD compliance history, major repairs and alterations, resolved squawks and the printable status report.
+
+Give it a label and optionally an expiry. Documents only appear if their visibility allows it (see [Documents](documents.md)). Delete a link to revoke it. An aircraft can have up to 10.
+
+## Records package
+
+**Download records package** builds a zip for the FAA, a buyer or a new maintainer: every logbook entry as a PDF with its signatures, a signature register, the change history, the status report, the current recordkeeping procedures, and the data archive.
+
+## Backup and transfer
+
+**Download .sam.zip** exports the whole aircraft with its files. Anyone can load it with **Fleet → Import** (in this app or the original Simple Aircraft Manager) to make a copy they own, for example when the aircraft is sold. Use a new tail number if the original is already in that app.
+
+## Activity
+
+The **Activity** tab lists everything done on the aircraft and by whom. **Record history** shows every change to the maintenance records field by field (see [Electronic records and signing](records.md)).
diff --git a/docs/guide/squawks.md b/docs/guide/squawks.md
new file mode 100644
index 0000000..ee773ea
--- /dev/null
+++ b/docs/guide/squawks.md
@@ -0,0 +1,22 @@
+# Squawks
+
+A squawk is a problem found with the aircraft. Anyone on the aircraft can report one.
+
+## Report a squawk
+
+**Report Squawk** asks for the issue, a priority, optionally the component, attachments (photos, PDFs) and notes.
+
+| Priority | Meaning |
+|---|---|
+| **Ground Aircraft** | The aircraft isn't airworthy until it's resolved. |
+| **Fix Soon** | Fix before it gets worse. |
+| **Fix at Next Inspection** | Can wait for the next inspection. |
+| **Fix Eventually** | Minor. |
+
+## Defer an inoperative item (91.213(d))
+
+For inoperative equipment that isn't required, **Defer** records the decision. You confirm each condition of 14 CFR 91.213(d): not required by the type certificate, equipment list, 91.205 or another rule, nor by an AD; removed or deactivated and placarded *Inoperative*; and that a pilot or mechanic has determined it isn't a hazard. You record who decided and in which role. A deferred squawk no longer grounds the aircraft. **Undo deferral** (owners) reverses it.
+
+## Resolve a squawk
+
+Owners choose **Resolve**. You can record the fix as a logbook entry at the same time: the date, logbook, airframe total time, work performed and who signed it off. A resolved squawk can be **Reopen**ed.
diff --git a/test/integration/user_guide_test.rb b/test/integration/user_guide_test.rb
new file mode 100644
index 0000000..e90a1c0
--- /dev/null
+++ b/test/integration/user_guide_test.rb
@@ -0,0 +1,44 @@
+require "test_helper"
+
+# The user guide in docs/guide, shown under /help.
+class UserGuideTest < ActionDispatch::IntegrationTest
+ setup { sign_in create_user("pilot@example.com") }
+
+ test "every guide page renders with the contents and links between pages" do
+ get help_path
+ assert_response :success
+ assert_select "h1", "User guide"
+ HelpGuide::ORDER.each do |slug|
+ assert HelpGuide.find(slug), "docs/guide/#{slug}.md is missing"
+ get(slug == "README" ? help_path : help_page_path(slug))
+ assert_response :success
+ assert_select "nav[aria-label='Help pages'] a", HelpGuide::ORDER.size * 2
+ assert_no_match(/href="[a-z-]+\.md/, response.body, "#{slug} has an unconverted .md link")
+ end
+ get help_page_path("logbook")
+ assert_select "a[href='/help/records#mistakes']"
+ end
+
+ test "links in the guide point at real pages and headings" do
+ HelpGuide.pages.each do |page|
+ page.markdown.scan(/\]\(([a-z-]+|README)\.md(?:#([a-z0-9-]+))?\)/).each do |slug, anchor|
+ target = HelpGuide.find(slug)
+ assert target, "#{page.slug} links to missing #{slug}.md"
+ assert_includes HelpGuide.html(target, link: nil), %(id="#{anchor}"), "#{page.slug} links to missing ##{anchor} in #{slug}" if anchor
+ end
+ end
+ end
+
+ test "only guide pages can be opened" do
+ get "/help/secrets"
+ assert_response :not_found
+ get records_help_path
+ assert_response :success
+ assert_includes response.body, "Correct this entry"
+ end
+
+ test "the guide is in the menu" do
+ get root_path
+ assert_select "a[href='/help']", minimum: 1
+ end
+end