Repository Public
1<!--2ORIX Docs3File: README.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78<div align="center">910<img src="https://git.spboucher.ai/raw/orix-docs/main/docs/assets/orix-docs-icon-256.png" width="128" height="128" alt="ORIX Docs icon: an indigo ring on a dark ink plate, a white page with text lines and an amber caret">1112# ORIX Docs1314**ORIX Docs — Write Without Limits.**1516ORIX Docs is a native macOS word processor with real pagination, styles, tables, equations, citations, track changes and document comparison.17It works entirely on the Mac: no account, no telemetry and no network code, with DOCX and PDF as first-class exchange formats.181920212223242526272829303132333435363738394041</div>4243<sub>4445| Metric badge | Exact value in the source | Source file |46|---|---|---|47| Engine tests | 582 tests, 85 suites, 10 targets, result `passed`, 0 issues | [`docs/reports/test-results.json`](docs/reports/test-results.json) |48| Interaction scenarios | 19 scenarios, 19 passed, 0 failed | [`docs/reports/test-results.json`](docs/reports/test-results.json), [`docs/reports/selftest-release.json`](docs/reports/selftest-release.json) |49| Engine line coverage | 92.9 % (26198 of 28196 lines; application target not included) | [`docs/reports/coverage.json`](docs/reports/coverage.json) |50| Version, minimum macOS | 1.0.0 (build 2), `minimumSystemVersion` 15.0 | `dist/release.json` (not committed; copied into [`docs/release/distribution.md`](docs/release/distribution.md)), [`project.yml`](project.yml) |51| Notarization | application and disk image both `Accepted` | `dist/release.json`, copied into [`docs/release/notarization.md`](docs/release/notarization.md) |52| DMG size | 30810813 bytes | `dist/release.json`, copied into [`docs/release/distribution.md`](docs/release/distribution.md) |53| DOCX round trip | 19 documents; text integrity after two cycles 100.00 % (word-weighted, 526 words) | [`docs/reports/docx-compatibility.md`](docs/reports/docx-compatibility.md) |54| PDF export · 487 pages | `pdf_export_ms` 1395.518458 | [`docs/reports/benchmarks.json`](docs/reports/benchmarks.json) |55| Open + first layout · 487 pages | `open_and_first_layout_ms` 452.972959 | [`docs/reports/benchmarks.json`](docs/reports/benchmarks.json) |56| Keystroke relayout · 487 pages | `keystroke_relayout_ms.median` 14.027374999999999 | [`docs/reports/benchmarks.json`](docs/reports/benchmarks.json) |5758There is no continuous-integration service and therefore no "build passing" badge; the test badges quote the last recorded local run. Badge rendering on the SPB Git website has not been checked (see [Release Status](#release-status)).5960</sub>6162<div align="center">6364<img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/01-main-editor.png" alt="ORIX Docs main window in Writing mode: outline sidebar on the left, a paginated research report in the centre, the Typography inspector on the right" width="100%">6566<sub>The main window in Writing mode on the Research Report template: outline, paginated canvas with ruler, Typography inspector, status bar with page, word and character counts.</sub>6768</div>6970### Highlights7172- **A real page.** A Core Text typesetter and an in-house paginator: sections, columns, headers and footers, footnotes, widow and orphan control, keep rules, tables that split by rows with repeated headers.73- **Structure first.** Paragraph and character styles with inheritance, six themes, numbered headings, an outline that can move whole sections.74- **Academic tooling.** LaTeX equations, captions, cross-references, a per-document reference library (BibTeX, RIS, CSL-JSON) and six built-in citation styles.75- **Review.** Track changes with per-change accept and reject, comments with replies, and a document comparison that produces a merged document of tracked changes.76- **Honest exchange.** DOCX import and export with a warning for everything approximated or dropped; vector PDF with outline, links and structure tags; Markdown, HTML, RTF and plain text.77- **Private by construction.** No account, no telemetry, no network code. On-device writing assistance only where the system provides it, always as a proposal to accept or reject.7879---8081## Table of Contents82831. [Overview](#overview)842. [ORIX Philosophy](#orix-philosophy)853. [Application Preview](#application-preview)864. [Editing Engine](#editing-engine)875. [Page Layout](#page-layout)886. [Typography](#typography)897. [Styles](#styles)908. [Tables](#tables)919. [Images and Objects](#images-and-objects)9210. [Mathematics](#mathematics)9311. [Academic Writing](#academic-writing)9412. [Long Documents](#long-documents)9513. [Track Changes](#track-changes)9614. [Document Comparison](#document-comparison)9715. [DOCX Compatibility](#docx-compatibility)9816. [PDF Publishing](#pdf-publishing)9917. [Native Format](#native-format)10018. [Autosave](#autosave)10119. [Templates](#templates)10220. [Publishing Studio](#publishing-studio)10321. [Local AI](#local-ai)10422. [Research Assistant](#research-assistant)10523. [Document Auditor](#document-auditor)10624. [Automation](#automation)10725. [Architecture](#architecture)10826. [Technology Stack](#technology-stack)10927. [Installation](#installation)11028. [Build Instructions](#build-instructions)11129. [Testing](#testing)11230. [Benchmarks](#benchmarks)11331. [Privacy](#privacy)11432. [Accessibility](#accessibility)11533. [Localization](#localization)11634. [Roadmap](#roadmap)11735. [Release Status](#release-status)11836. [Known Limitations](#known-limitations)11937. [ORIX Ecosystem](#orix-ecosystem)12038. [License](#license)121122---123124## Overview125126ORIX Docs 1.0.0 is a document-based macOS application (`ai.spboucher.orix.docs`) for macOS 15.0 or later. It is a thin SwiftUI + AppKit shell over `ORIXDocsKit`, a Swift package of eleven engine targets that do not import SwiftUI and can be built, tested and benchmarked from the command line ([architecture overview](docs/architecture/overview.md)).127128| | |129|---|---|130| Native document | `.orixdoc` — a single ZIP file with a SHA-256 manifest ([persistence](docs/architecture/persistence.md)) |131| Opens | `.orixdoc`, DOCX, RTF, Markdown, HTML, plain text, PDF (text only) |132| Exports | `.orixdoc`, DOCX, PDF, RTF, Markdown, HTML, plain text |133| Interface languages | English, Canadian French |134| Workspace modes | Writing, Page Layout, Review, Academic, Publishing, Focus |135| Command line | `orixdocs` (convert, audit, stats, compare, workflow), bundled in the application |136| Network use | None |137138What this README states is backed by a file in the repository; where something was not done or not verified, it says so. The consolidated list is in [Known Limitations](#known-limitations).139140## ORIX Philosophy141142ORIX applications share three commitments, described in the [brand guidelines](docs/design/brand-guidelines.md) and the [design system](docs/design/design-system.md):143144- **The document belongs to its author.** Files stay on the Mac, in a documented open container. Foreign files open as untitled copies; the original is never written ([persistence](docs/architecture/persistence.md#foreign-files-open-as-untitled-documents)).145- **Nothing is lost silently.** Every importer and exporter reports what it approximated or dropped as a warning, and the export sheet shows those warnings before the file is written.146- **Calm, native tools.** One accent pair (ink indigo `#4F46E5`, page amber `#F59E0B`), fixed tokens for colour, spacing and type, and modes that change which panels are shown — never the document.147148The competitive position, including where established products remain ahead, is set out in the [competitive analysis](docs/research/competitive-analysis.md).149150## Application Preview151152> Images in this README are addressed by branch (`…/raw/orix-docs/main/…`): the SPB Git forge throttles commit-pinned image URLs, which left part of the screenshots unloaded on a first visit. The files themselves are in [`docs/screenshots/`](docs/screenshots/).153154<table>155<tr>156<td width="50%"><img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/00-template-chooser.png" alt="New Document window with template categories on the left and first-page thumbnails of the Blank, Business letter and Academic paper templates"></td>157<td width="50%"><img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/02-writing-mode.png" alt="Writing mode on the Book manuscript template: a chapter opening with a drop cap, the outline sidebar, the inspector hidden"></td>158</tr>159<tr>160<td><sub><b>Template chooser.</b> Sixteen templates in six categories; each thumbnail is the first page of the template as laid out by the engine. The document language is chosen here.</sub></td>161<td><sub><b>Writing mode.</b> The Book manuscript template with a drop cap and a centred chapter title; the inspector is hidden.</sub></td>162</tr>163<tr>164<td width="50%"><img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/15-light-mode.png" alt="Light appearance: the Newsletter template in two columns with the Styles inspector showing six themes"></td>165<td width="50%"><img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/16-dark-mode.png" alt="Dark appearance: the same Newsletter document with dark chrome; the page and the style previews stay white"></td>166</tr>167<tr>168<td><sub><b>Light appearance.</b> The Newsletter template, Pages sidebar and Styles inspector.</sub></td>169<td><sub><b>Dark appearance.</b> The same window. The chrome follows the system appearance; the page stays white, as it will print, and so do the theme and style preview cards.</sub></td>170</tr>171</table>172173<div align="center">174<img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/17-focus-mode.png" alt="Focus mode: all bars and panels hidden, only the page remains, with paragraphs other than the caret's dimmed and a close button in the corner" width="80%">175176<sub><b>Focus mode.</b> Bars, sidebar, ruler, inspector and status bar are hidden and the paragraphs other than the caret's are dimmed; Escape or the close button returns to Writing.</sub>177</div>178179All screenshots in this document are PNG captures of the application's own windows, rendered by AppKit through the launch options driven by [`Scripts/screenshots.sh`](Scripts/screenshots.sh); nothing is composited or retouched.180181## Editing Engine182183The editor is not an `NSTextView`. It is a value-type document model (`DocModel`), an editing engine that transforms it (`DocumentEditor`) and a custom `NSView` (`EditorCanvasView`) that implements `NSTextInputClient` ([text engine](docs/architecture/text-engine.md)).184185- **Value-type model.** Undo is a stack of document values; snapshots share storage with their successors. Typing is coalesced into one undo step per burst.186- **Unicode-safe addressing.** Every offset is a UTF-16 offset aligned on a composed-character boundary; a ZWJ emoji is deleted as one character (self-test scenario 2).187- **Input.** Keyboard movement and selection by character, word, line, paragraph and document; input-method composition (marked text); mouse selection with double and triple click; copy, cut and paste with native, RTF, HTML and plain-text flavours; drops of images, PDF files and text.188- **Typing aids.** Smart quotes (guillemets with no-break spaces in French) and em dashes; spelling through `NSSpellChecker` with guesses, Ignore and Learn.189- **Find and replace** in its own panel, honouring change tracking.190191Not provided by the custom view: grammar checking, autocorrection, text replacement, Writing Tools, Look Up, dragging text, the system find bar, and a split caret for bidirectional text ([limits](docs/architecture/text-engine.md#15-limits)).192193## Page Layout194195<div align="center">196<img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/03-page-layout.png" alt="Page Layout mode on the Thesis template: page thumbnails with roman numerals on the left, a page with a numbered heading, a figure placeholder and a numbered equation, the Document inspector with paper, margins, columns and header settings" width="100%">197198<sub><b>Page Layout mode.</b> The Thesis template at 70 %: thumbnails with their page numbers, and the Document inspector for the current section (paper, orientation, margins, columns, header and footer distances).</sub>199</div>200201`DocLayout` typesets paragraphs with Core Text and flows them into pages with its own paginator ([layout engine](docs/architecture/layout-engine.md), [pagination](docs/architecture/pagination.md)).202203- Sections with their own paper size, orientation, margins, columns and page-number format; next-page, odd/even and continuous section breaks; page and column breaks.204- Headers and footers with first-page and odd/even variants, page number, page count and running-heading fields.205- Footnotes at the foot of the column of their reference; endnotes after the body.206- Widow and orphan control, keep lines together, keep with next, page break before.207- Floating images and shapes with square, top-and-bottom, behind-text and in-front wrapping.208- Page backgrounds, borders and watermarks.209- Screen and print paginate identically (`screenAndPrintLayoutsPaginateIdentically`).210211Limits worth knowing: rows do not split across pages, footnotes do not split, columns are not balanced, and line breaking is first-fit ([pagination limits](docs/architecture/pagination.md#limits), [layout limits](docs/architecture/layout-engine.md#limits)).212213## Typography214215<div align="center">216<img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/04-typography-studio.png" alt="Typography inspector beside an academic paper: font family, weight, size, style toggles, colours, tracking, baseline shift, kerning, ligatures, language, alignment and line spacing; a three-rule table and a numbered equation on the page" width="100%">217218<sub><b>Typography inspector.</b> Character and paragraph settings for the selection in the Academic paper template; the page shows footnotes, a three-rule table and a numbered display equation.</sub>219</div>220221Character formatting covers font family, weight (100–900), size, bold, italic, underline, strikethrough, superscript and subscript, small caps and all caps, text colour, highlight, tracking, baseline shift, kerning, ligatures and a language tag per run. Paragraph formatting covers alignment, indents, spacing, line spacing (multiple, exact, at least), tab stops with leaders, hyphenation, drop caps, shading, borders and right-to-left direction (`CharProps` and `ParaProps` in `DocModel/Properties.swift`).222223Small capitals and bold depend on what the font offers; only italic is synthesised. Hyphenation uses one language per paragraph ([layout limits](docs/architecture/layout-engine.md#limits)).224225## Styles226227<div align="center">228<img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/20-styles.png" alt="Styles inspector on the Technical manual template: style at the selection, update-to-match and new-style buttons, six theme cards with Technical selected, numbered headings switched on, and the paragraph style list" width="100%">229230<sub><b>Styles inspector.</b> The Technical manual template: the style at the selection (marked "Modified" when direct formatting differs), the six themes, numbered headings and the paragraph style list.</sub>231</div>232233Formatting is resolved as document defaults → paragraph style chain (`basedOn`) → character style chain → direct properties. Built-in style identifiers equal Word's (`Normal`, `Heading1`, `Title`, `Caption`…), which keeps semantics through a DOCX round trip ([overview](docs/architecture/overview.md#the-document-model-in-one-page)). A style can be updated from the selection or created from it; six themes (ORIX, Classic, Modern, Academic, Editorial, Technical) re-derive the built-in styles.234235## Tables236237<div align="center">238<img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/05-tables.png" alt="Table inspector beside a financial report: a five-by-four table with two rows of cells selected, table styles Grid, Banded, Lined, Academic and Plain, header row switch, row and column commands, merge, split, column width and sorting" width="100%">239240<sub><b>Table inspector.</b> The Financial report template with a cell selection: five table styles, header row, row and column commands, merge and split, column width, sorting.</sub>241</div>242243- Insert, delete, merge and split; horizontal spans and Word-style vertical merges; column resizing by dragging.244- Table styles (Grid, Banded, Lined, Academic, Plain), header rows repeated on continuation pages, cell shading and vertical alignment.245- Sorting of body rows and cell formulas with recalculation.246- Captions with sequence fields and a generated list of tables.247248Cells hold paragraphs only (no nested tables); a row never splits across pages; table structure changes are not tracked ([text engine limits](docs/architecture/text-engine.md#15-limits), [pagination limits](docs/architecture/pagination.md#limits)).249250## Images and Objects251252Images are stored once per document and referenced by identifier. PNG, JPEG, GIF, TIFF, HEIC and PDF assets are drawn; a PDF asset is drawn as vector content (its first page). Images can be inline or floating, cropped and rotated, and carry alternative text. Shapes are rectangle, rounded rectangle, ellipse, line, arrow and callout, with a one-line label ([layout engine: the page renderer](docs/architecture/layout-engine.md#the-page-renderer), [DOCX: images, shapes, drawings](docs/compatibility/docx.md#images-shapes-drawings)).253254Not available: charts, SmartArt, grouped shapes, text boxes as objects, picture effects. Inline objects are unbreakable boxes: one wider than the line overflows it ([layout limits](docs/architecture/layout-engine.md#limits)).255256## Mathematics257258<div align="center">259<img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/06-equation-editor.png" alt="Edit Equation sheet: a typeset preview of a regression equation, its LaTeX source, an Inline or Display switch and a palette of Greek letters with tabs for operators, relations, arrows, fractions and sums" width="70%">260261<sub><b>Equation sheet.</b> LaTeX source with a live preview typeset by the same renderer as the page, inline or display, and a symbol palette.</sub>262</div>263264Equations are LaTeX math typeset by [SwiftMath](https://github.com/mgriebling/SwiftMath) as vector glyphs in the page's own drawing context, on screen and in PDF. Display equations can be numbered and cross-referenced. On DOCX export and import, LaTeX is converted to and from OMML; HTML export can carry MathML ([layout engine: equations](docs/architecture/layout-engine.md#equations), [DOCX: equations](docs/compatibility/docx.md#equations)).265266This is a **subset of LaTeX math mode**, not a TeX engine: user macros, `align`, `\underbrace`, `\overset`, `\boxed` and `\tag` are among the constructs the library does not support ([technology evaluation, section 6](docs/research/technology-evaluation.md#6-math)). An expression that does not parse is shown as its source in red rather than vanishing, and expressions outside safe bounds are refused before they reach the library ([security](docs/security.md#mathematics)).267268## Academic Writing269270<table>271<tr>272<td width="50%"><img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/07-academic-writing.png" alt="Academic mode: an academic paper with a captioned three-rule table and a numbered equation, the References inspector with citation style APA 7th edition, a two-entry reference library and buttons for citation, bibliography, captions, lists and cross-reference"></td>273<td width="50%"><img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/08-citation-manager.png" alt="Insert Citation sheet: a searchable list of the document's two references on the left, the in-text citation preview and the per-work locator area on the right, with Import References and Add Reference buttons"></td>274</tr>275<tr>276<td><sub><b>Academic mode.</b> The References inspector: citation style, the document's reference library, and commands for citations, bibliography, captions, lists of figures and tables, and cross-references.</sub></td>277<td><sub><b>Insert Citation.</b> Works are chosen from the document's library; locator, prefix and suffix are set per work.</sub></td>278</tr>279</table>280281- **Reference library** per document; import and export of BibTeX / BibLaTeX, RIS and CSL-JSON, with duplicate detection on key, DOI, and title plus year.282- **Six built-in citation styles**: APA 7, Chicago 17 author-date, MLA 9, IEEE, a generic numeric style and Vancouver. Citations and the bibliography are computed, never stored as text.283- **Captions, cross-references, footnotes and endnotes**, numbered headings, generated contents and lists of figures and tables.284285This is **not a CSL processor**: a `.csl` file cannot be loaded, titles are printed as stored, and there are no note-based styles. The deviations from each published guide are listed and tested in the [references engine](docs/architecture/references.md#known-deviations) document.286287## Long Documents288289The outline sidebar lists headings with their numbers and moves a heading with everything under it; the Pages sidebar shows lazy, debounced thumbnails; contents, lists of figures and tables, page cross-references and running heads are recomputed by a multi-pass layout that stops when page references are stable (at most four passes) ([pagination: generated blocks and convergence](docs/architecture/pagination.md#generated-blocks-and-convergence)).290291Measured on a generated 487-page document (177162 words, 80 tables, 320 footnotes, 80 equations): a cold layout in 436.577292 ms and a median relayout after a keystroke of 14.027374999999999 ms — see [Benchmarks](#benchmarks) for the meaning of each figure. Every edit re-flows the body from the first block; what keeps this fast is the paragraph cache, not incremental pagination. **No unlimited page count is promised.**292293## Track Changes294295<table>296<tr>297<td width="50%"><img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/09-review-mode.png" alt="Review mode: the Review sidebar with reviewer name, track changes and markup switches, four changes by two authors with accept and reject buttons and two comments; the Auditor inspector reports one warning for pending tracked changes"></td>298<td width="50%"><img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/10-track-changes.png" alt="Tracked changes at 130 percent: a highlighted formatted phrase, an underlined inserted sentence in the author's colour, and change bars in the margin"></td>299</tr>300<tr>301<td><sub><b>Review mode.</b> Changes listed by author and kind with per-change accept and reject, comments with replies, and the auditor noting that tracked changes are pending.</sub></td>302<td><sub><b>Markup on the page.</b> An insertion underlined in its author's colour, a comment tint, and change bars in the margin. Insertions are underlined and deletions struck through, so markup does not rely on colour alone.</sub></td>303</tr>304</table>305306Tracked: inserted and deleted text, paragraph marks, character formatting, pasted content and replacements. Each change records its author and date; a burst of typing is one change. Accept and reject work per change, per selection of changes, or for all ([text engine: accepting and rejecting changes](docs/architecture/text-engine.md#6-accepting-and-rejecting-changes)).307308**Not tracked:** table structure, inserted or deleted breaks and other atomic blocks, paragraph formatting, styles and lists, link and character-style changes, object resizing and section moves ([what is not tracked](docs/architecture/text-engine.md#5-editing-operations)).309310## Document Comparison311312<div align="center">313<img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/11-document-comparison.png" alt="Comparison window for original.md and revised: a summary of four modified blocks and one moved paragraph with similarity 85.0 percent, a change list, and original and revised columns side by side with deleted words struck through, inserted words underlined and the moved paragraph marked on both sides" width="100%">314315<sub><b>Comparison window.</b> Two Markdown files compared: a change list, aligned original and revised columns with word-level insertions and deletions, a moved paragraph, a changed table cell, and a button that opens the merged document as tracked changes.</sub>316</div>317318`DocReview` aligns blocks with a patience and Myers diff, pairs modified paragraphs by similarity, detects moved paragraphs, diffs words inside pairs, and reports formatting, style and structure changes separately from content. The result is a side-by-side view, a report (Markdown or a formatted document), and a **merged document in which every difference is a tracked change** ([document comparison](docs/architecture/review.md)).319320Tested invariant, including 40 seeded random edit scripts: accepting every change gives the revised text, rejecting every change gives the original text. Differences the model cannot track (paragraph style, table properties, page setup) are reported but cannot be rejected ([limits of the invariant](docs/architecture/review.md#the-merged-document)).321322## DOCX Compatibility323324ORIX Docs reads and writes WordprocessingML with its own engine ([DOCX architecture](docs/architecture/docx.md), [feature-by-feature table](docs/compatibility/docx.md)). **Perfect Word compatibility is not claimed, and Microsoft Word itself was not used in any test**; the files were checked with pandoc 3.9.0.2, macOS `textutil` and LibreOffice 26.8.2.2.325326Measured results on the reference corpus, from [`docs/reports/docx-compatibility.md`](docs/reports/docx-compatibility.md) (generated 2026-11-21T06:47:05Z):327328| Measure | Result |329|---|---|330| Documents | 19 |331| Imported without error | 19 / 19 |332| Model equal after the first cycle / the second cycle | 19 / 19, 19 / 19 |333| Words in the corpus | 526 |334| Text integrity after two cycles (word-weighted) | 100.00 % |335| Feature checks passed / failed (feature × document) | 172 / 0 |336| Import warnings: info / approximated / dropped | 11 / 8 / 26 |337| pandoc reads our export | 19 / 19 (mean in-order word agreement 97.9 %) |338| `textutil` reads our export | 19 / 19 (mean word agreement 96.4 %) |339| LibreOffice converts our export to PDF | 19 / 19 |340341How to read this:342343- The corpus is **small and mostly synthetic** (pandoc and LibreOffice output, hand-authored OOXML, one ORIX-generated document). It measures the engine on listed features, not on arbitrary real-world documents.344- "Model equal" proves that ORIX Docs reads back what it writes. It does not prove that another application renders the file the same way. **Layout (line breaks, pagination, fonts) is not measured anywhere.**345- Unsupported content is disclosed, not hidden: charts, SmartArt, embedded objects, linked pictures, macros, tracked moves, nested tables and text boxes are dropped or approximated **with a named warning**, shown when the file opens and before an export is written.346- Macros, OLE and ActiveX parts are never executed and never preserved; external targets are never fetched ([security](docs/security.md)).347348A DOCX file opens as an untitled document: saving creates an `.orixdoc`, and writing a DOCX is an explicit export.349350## PDF Publishing351352<div align="center">353<img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/18-export-sheet.png" alt="Export sheet with seven formats and PDF selected: options for bookmarks from headings, structure tags, crop marks with bleed and a page range, and a notice that tracked changes are shown as accepted and two comments are not included" width="70%">354355<sub><b>Export sheet.</b> Seven formats; for PDF, bookmarks from headings, structure tags, crop marks and a page range. The lower panel states what this format changes before the file is written.</sub>356</div>357358A PDF is the paginated layout drawn by the same renderer that paints the screen, into a Core Graphics PDF context: vector text with embedded fonts, vector equations, images at their source resolution, external and internal links, named destinations, document metadata, an outline from the headings, structure tags, optional crop marks and a page range ([PDF publishing](docs/architecture/pdf.md)). Pending tracked changes are published as accepted on a copy; comments are not exported.359360**No conformance to PDF/A or PDF/UA is claimed.** No validator was run, no output intent or XMP metadata is written, and the tag structure is partial: tables carry no row or cell structure, lists are flat, headers and footers are untagged, and no document language is written ([what is not claimed](docs/architecture/pdf.md#what-is-not-claimed), [known limits](docs/architecture/pdf.md#known-limits)). There is no colour management and no CMYK conversion.361362## Native Format363364`.orixdoc` is one ZIP archive: a `mimetype` entry stored first, a `manifest.json` listing every other entry with its size and SHA-256, `document.json` (the model, sorted keys), `assets/` and `preserved/` (uninterpreted parts of an imported DOCX) ([persistence](docs/architecture/persistence.md#the-native-format-orixdoc)).365366- **Strict reading**: sizes and checksums are verified before the document is decoded; a newer container or schema version is refused rather than guessed.367- **Recovery**: a damaged file is read as far as its intact entries allow and opens with a warning; recovery never invents a document.368- **Deterministic writing** for a given document, generator and creation date, which makes files diffable.369- **Schema migrations** run on a JSON tree on every read; only schema version 1 exists today.370371The format has no encryption and no digital signature: the SHA-256 manifest detects corruption, not tampering. The whole file is rewritten on each save.372373## Autosave374375The application is a classic `NSDocument` application: autosave in place, versions (Browse All Versions), Revert, Duplicate, Rename and Move To come from AppKit. The autosave delay is 5 seconds. Saving encodes a value snapshot of the model on a background thread, so later edits cannot corrupt a write in progress ([autosave, versions and recovery](docs/architecture/persistence.md#autosave-versions-and-recovery)).376377Recorded check: `"recovery": "PASS: autosaved text survived SIGKILL"` in [`docs/reports/test-results.json`](docs/reports/test-results.json) — text typed into a saved document was on disk after the process was killed with `kill -9` ([what the test does and does not prove](docs/architecture/persistence.md#recovery-after-a-kill)). Not covered by a test: never-saved untitled documents, a kill in the middle of a write, power loss.378379## Templates380381Sixteen templates in six categories, each a real document with its own style sheet (`DocTemplates`): Blank; Business letter, Proposal, Financial report, Meeting minutes, Project report, Invoice; Academic paper, Research report, Thesis; Legal memorandum; Résumé, Cover letter; Technical manual, Book manuscript, Newsletter. Templates exist in English and French, chosen in the [template chooser](#application-preview). Every template is laid out and published to PDF by `TemplateRenderingTests.everyTemplateLaysOutAndPublishes`.382383## Publishing Studio384385<div align="center">386<img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/12-publishing-studio.png" alt="Publishing mode on the Technical manual template: page thumbnails, a table of contents page with dot leaders, and the Publish inspector with document summary, typography presets Book, Report, Manuscript and Compact, and page template buttons" width="100%">387388<sub><b>Publishing mode.</b> The Technical manual template: page thumbnails, a generated table of contents with leaders, and the Publish inspector with document properties, four typography presets and page elements.</sub>389</div>390391Publishing mode gathers what prepares a document for output: document properties, four typography presets (Book, Report, Manuscript double-spaced, Compact) that change the theme, the Body style and the margins in one undoable step, and one-click contents, lists, bibliography and breaks. Export goes through the [export sheet](#pdf-publishing).392393## Local AI394395<div align="center">396<img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/13-local-ai.png" alt="Intelligence inspector: on-device model ready, a Rewrite proposal for a 22-word selection shown as word-level deletions and insertions, with Accept, Reject, Insert Below, Copy and Regenerate, and a rule-based text analysis section below" width="100%">397398<sub><b>Intelligence inspector.</b> A rewrite proposed by the on-device model for the selected paragraph, shown as changes with Accept, Reject, Insert Below, Copy and Regenerate; the rule-based tools are listed below it.</sub>399</div>400401Writing assistance uses Apple's Foundation Models framework with the **on-device** `SystemLanguageModel` only.402403| | |404|---|---|405| Requirements | macOS 26 or later, on a Mac and in a region where Apple Intelligence is available and enabled. On macOS 15 the feature is unavailable and says why. |406| Actions | Summarise, rewrite, improve clarity, adjust tone (formal, friendly, concise, academic), suggest headings, outline, action items, explain, suggest structure |407| Behaviour | Every result is a **proposal** with Accept / Reject; nothing is applied silently; one Undo restores the original text |408| Long texts | Processed part by part or by map-reduce within the model's context window; detail is lost on the way and the panel says which strategy ran |409| Guarantee | The server-backed model type of the same framework must not appear in the sources: `OnDeviceOnlyTests.noServerBackedModelTypeInTheSources` scans `App/Sources` and the package sources for it |410| Verified on | The build machine (Apple M5 Max, macOS 27.0): model reported available, context size 8192 tokens ([technology evaluation, section 9](docs/research/technology-evaluation.md#9-local-ai)) |411412Limits, stated plainly:413414- **Quality is not measured.** No evaluation of the model's output was done and nothing is claimed about it. Output changes with operating-system updates.415- The "concise" tone action often returns the text unchanged; the panel then reports that the model proposed no edit.416- Latency as recorded by the engineer: 1.7–8.5 s per action on a selection of about 235 tokens, **measured while the machine was under load — indicative only**. These figures are not stored in a report file in the repository; the opt-in test `OnDeviceModelTests` (`ORIX_AI_TESTS=1`) reproduces the measurement.417- The model may decline a request; the text is then left untouched.418419## Research Assistant420421The research tools are rule-based and quote the document; nothing is generated ([auditor and research assistant](docs/architecture/audit.md#research-assistant)). They work without the language model:422423- search across body, tables, notes, headers and footers, with whole-word, case, diacritic and regular-expression options;424- undefined acronyms, repeated wording, unreferenced figures and tables, cited passages, action items;425- readability, language identification per paragraph and related-paragraph search on the NaturalLanguage framework (`App/Sources/Intelligence/TextTools.swift`).426427Repeated-wording and related-paragraph results depend on the language models installed with macOS ([limits](docs/architecture/audit.md#limits)).428429## Document Auditor430431<div align="center">432<img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/14-document-auditor.png" alt="Auditor inspector on the Thesis template with the Academic profile: zero errors, five warnings and three notes; the warnings list unusual page breaks on nearly empty pages, each with its page number and a Show button" width="100%">433434<sub><b>Document auditor.</b> The Thesis template audited with the Academic profile: findings by severity, each with evidence from the document, its page and a Show button.</sub>435</div>436437`DocAudit` runs deterministic checks and returns findings with evidence quoted from the document: heading hierarchy, empty and duplicate headings, broken cross-references, missing captions and alternative text, inconsistent formatting, unresolved comments, pending tracked changes, missing or orphaned bibliography entries, unusual page breaks, overflowing tables, missing page numbers, long sentences, double spaces and missing metadata. Four profiles (standard, academic, business, minimal); findings and the report exist in English and French ([checks and thresholds](docs/architecture/audit.md#checks-and-thresholds)).438439## Automation440441<div align="center">442<img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/19-automation.png" alt="Workflows sheet: four built-in workflows on the left, the five steps of DOCX to styled PDF on the right, input choice between this document and files, output folder and a Run button" width="80%">443444<sub><b>Workflows sheet.</b> Four built-in workflows; the steps of the selected one in plain language; input, output folder and overwrite policy.</sub>445</div>446447Three surfaces on one engine ([automation](docs/development/automation.md)):448449| Surface | Status |450|---|---|451| **Workflows** — JSON sequences of document operations, on one document or a batch, with history | Implemented and tested |452| **`orixdocs`** — `convert`, `audit`, `stats`, `compare`, `workflow run`, `formats`; bundled at `ORIX Docs.app/Contents/Helpers/orixdocs` | Implemented and tested |453| **Shortcuts actions** — Convert Document, Export as PDF, Audit Document, Document Statistics | Compiled; **never run from the Shortcuts app** |454| **AppleScript** | Deferred; no scripting dictionary is shipped |455456```sh457orixdocs convert report.docx report.pdf --theme Academic --paper a4458orixdocs audit thesis.orixdoc --profile academic --json > findings.json459orixdocs compare v1.docx v2.docx --report changes.md --merged merged.orixdoc460orixdocs workflow run docx-to-styled-pdf inbox/*.docx --out published --jobs 4461```462463Workflows cannot run scripts or reach the network: the step vocabulary is closed, unknown step types are rejected at load time, and output paths are confined to the chosen folder ([security](docs/security.md#workflows)).464465## Architecture466467The diagrams below are Mermaid. Mermaid blocks are emitted as diagrams by the SPB Git website (checked after publication; not reviewed visually by a person); the same structures are explained in prose in [`docs/architecture/`](docs/architecture/overview.md).468469### 1. Modules470471```mermaid472flowchart TD473 App["ORIX Docs app: SwiftUI + AppKit"] --> Automation[DocAutomation]474 CLI["orixdocs command-line tool"] --> Automation475 Automation --> DOCX[DocDOCX]476 Automation --> Formats[DocFormats]477 Automation --> Layout[DocLayout]478 Automation --> References[DocReferences]479 Automation --> Review[DocReview]480 Automation --> Audit[DocAudit]481 Automation --> Templates[DocTemplates]482 DOCX --> Container[DocContainer]483 Formats --> Container484 Layout --> Math[DocMath]485 Math --> SwiftMath["SwiftMath (third party)"]486 Container --> Model[DocModel]487 Math --> Model488 References --> Model489 Review --> Model490 Audit --> Model491 Templates --> Model492```493494Details: [architecture overview](docs/architecture/overview.md).495496### 2. Text editing497498```mermaid499sequenceDiagram500 participant W as NSWindow501 participant C as EditorCanvasView502 participant S as DocumentSession503 participant E as DocumentEditor504 participant P as Paginator505 W->>C: keyDown506 C->>C: input context, insertText or doCommand507 C->>S: perform508 S->>E: editing operation509 S->>S: register undo unless coalesced510 S->>S: store model for background saving511 S->>P: layout with cache and previous layout512 P-->>S: DocumentLayout513 S->>C: layoutChanged514 C->>C: redraw visible pages and overlays515```516517Details: [text engine, section 8](docs/architecture/text-engine.md#8-from-key-press-to-pixels).518519### 3. Layout pipeline520521```mermaid522flowchart LR523 M[DocumentModel] --> N[Numbering]524 M --> PG[Paginator]525 N --> PG526 PG --> LC[LayoutCache]527 LC -->|miss| PL[ParagraphLayout]528 PL --> FC[FontCache]529 PL --> MR[MathRenderer]530 PG --> DL[DocumentLayout]531 DL --> PR[PageRenderer]532 DL --> GQ["Geometry queries"]533 PR --> SC[Screen]534 PR --> BM["Thumbnails and previews"]535 PR --> PDF["PDF context"]536```537538Details: [layout engine](docs/architecture/layout-engine.md).539540### 4. Pagination (simplified)541542```mermaid543flowchart TD544 A["Start a pass with page references from the previous pass"] --> B["Take the next block"]545 B --> C{"Fits in the column with its footnotes?"}546 C -->|yes| D["Place lines, apply widow, orphan and keep rules"]547 C -->|no| E["Close the column, place its footnotes, go to the next column or page"]548 E --> D549 D --> F{"More blocks?"}550 F -->|yes| B551 F -->|no| G["Place endnotes, headers and footers"]552 G --> H{"Page references stable, or fourth pass?"}553 H -->|no| A554 H -->|yes| I[DocumentLayout]555```556557Details: [pagination](docs/architecture/pagination.md).558559### 5. DOCX import and export560561```mermaid562flowchart LR563 F[".docx file"] --> Z["ZipReader with limits"]564 Z --> X["XML parts: no DOCTYPE, size and depth limits"]565 X --> I["Importer: styles, numbering, body, notes, comments, sections"]566 I --> M[DocumentModel]567 I --> W1["Warnings: approximated or dropped"]568 I --> PP["Preserved parts (allow-list)"]569 M --> EX["Exporter: body, notes, comments, styles, settings"]570 PP --> EX571 EX --> W2["Preflight warnings"]572 EX --> ZW["ZipWriter, fixed timestamps"]573 ZW --> O[".docx file"]574```575576Details: [DOCX engine](docs/architecture/docx.md).577578### 6. PDF publishing579580```mermaid581flowchart LR582 M[DocumentModel] --> C["Copy with pending changes accepted"]583 C --> L["Print layout: no markup, no comments"]584 L --> R[PageRenderer]585 R --> CTX["Core Graphics PDF context"]586 R --> H["Render hooks: links and structure tags"]587 H --> CTX588 L --> O["Outline and named destinations"]589 O --> CTX590 CTX --> P["PDF data"]591```592593Details: [PDF publishing](docs/architecture/pdf.md).594595### 7. Citation management596597```mermaid598flowchart LR599 B["BibTeX, RIS, CSL-JSON files"] --> IMP[BibliographyImporter]600 IMP --> MG["Merge: key, DOI, title and year"]601 MG --> LIB["Document bibliography"]602 LIB --> ENG[CitationEngine]603 CIT["Citation inlines in the text"] --> ENG604 ST["Citation style setting"] --> ENG605 ENG --> T["In-text citation text"]606 ENG --> BL["Generated bibliography paragraphs"]607 T --> LAY[Layout]608 BL --> LAY609```610611Details: [references engine](docs/architecture/references.md).612613### 8. Local AI proposal614615```mermaid616flowchart TD617 S["Selection and action"] --> A{"On-device model available?"}618 A -->|no| U["Explain why; rule-based tools remain"]619 A -->|yes| R[IntelligenceRunner]620 R --> F{"Fits the context window?"}621 F -->|yes| D["One request"]622 F -->|no| P["Part by part or map-reduce"]623 D --> O[Proposal]624 P --> O625 O --> V["Shown as changes, with unsupported passages flagged"]626 V -->|Accept| AP["One undoable edit"]627 V -->|Reject| X["Document untouched"]628```629630Details: `Packages/ORIXDocsKit/Sources/DocAutomation/Intelligence/`, [technology evaluation, section 9](docs/research/technology-evaluation.md#9-local-ai).631632### 9. Document persistence633634```mermaid635flowchart TD636 OP["Open a file"] --> T{"Native .orixdoc?"}637 T -->|yes| RD["Strict read: manifest, sizes, SHA-256"]638 RD -->|fails| RC["Recover intact entries, warn"]639 RD -->|ok| DOC["Document window"]640 RC --> DOC641 T -->|no| IM["Import: DOCX, RTF, Markdown, HTML, text, PDF text"]642 IM --> UN["Untitled copy; original never written"]643 UN --> DOC644 DOC --> ED[Edit]645 ED --> MS["ModelStore: latest value snapshot"]646 MS --> AS["Autosave in place, 5 s delay, background thread"]647 AS --> FILE[".orixdoc on disk, versions by AppKit"]648```649650Details: [persistence](docs/architecture/persistence.md).651652### 10. Review engine653654```mermaid655flowchart LR656 subgraph Tracking657 E["Edit with tracking on"] --> RV["Runs carry insertion, deletion or format revisions"]658 RV --> AR["Accept or reject: per change or all"]659 end660 subgraph Comparison661 O[Original] --> AL["Block alignment: patience and Myers diff"]662 R[Revised] --> AL663 AL --> PM["Pair modified blocks, detect moves"]664 PM --> TD["Word-level diff and formatting comparison"]665 TD --> MD["Merged document of tracked changes"]666 TD --> RP["Report and side-by-side view"]667 end668 MD --> AR669```670671Details: [text engine, sections 5–6](docs/architecture/text-engine.md#5-editing-operations), [document comparison](docs/architecture/review.md).672673## Technology Stack674675| Area | Choice | Why (see the [technology evaluation](docs/research/technology-evaluation.md)) |676|---|---|---|677| Language | Swift 6 language mode, strict concurrency `complete` | Value-type, `Sendable` model |678| Interface | SwiftUI panels and sheets, AppKit document architecture and canvas | `NSDocument` gives autosave, versions and file coordination |679| Text | Core Text typesetting, own paginator, custom `NSTextInputClient` view | TextKit 2 cannot flow text through pages with exact geometry |680| PDF | Core Graphics PDF context; PDFKit for printing and PDF text import | One renderer for screen and print |681| ZIP, DOCX, Markdown, HTML | Written in this repository | No suitable Swift library; hostile-input rules under our control |682| RTF | AppKit's RTF codec, plus own picture handling | Local, no WebKit |683| Math | SwiftMath, pinned by revision | Vector glyphs in the page's context |684| Citations | Own formatter for six styles | No maintained Swift CSL processor |685| Spelling, language analysis | `NSSpellChecker`, NaturalLanguage | System services, on device |686| On-device AI | Foundation Models, `SystemLanguageModel` only | No server-backed model |687| Project | XcodeGen (`project.yml`), Swift Package Manager | Reproducible project file |688| Build environment | Xcode 27.2, macOS 27.0, Apple M5 Max | As recorded in the [technology evaluation, section 0](docs/research/technology-evaluation.md#0-environment) |689690The only third-party dependency is SwiftMath. Automatic updates (Sparkle) were evaluated and are **not implemented in 1.0.0**.691692## Installation693694**Requirements:** macOS 15.0 or later. The application is a universal binary (arm64 + x86_64). It was developed and tested on Apple silicon only: **the Intel slice is built but untested.**695696Download from the [SPB Git release v1.0.0](https://git.spboucher.ai/orix-docs/releases): [ORIX-Docs-1.0.0.dmg](https://git.spboucher.ai/releases/orix-docs/v1.0.0/ORIX-Docs-1.0.0.dmg) · [ORIX-Docs-1.0.0.zip](https://git.spboucher.ai/releases/orix-docs/v1.0.0/ORIX-Docs-1.0.0.zip) · [SHA256SUMS.txt](https://git.spboucher.ai/releases/orix-docs/v1.0.0/SHA256SUMS.txt).697698| File | Size | SHA-256 |699|---|---|---|700| `ORIX-Docs-1.0.0.dmg` | 30810813 bytes | `94144d313c91a029c44f2dc34add72f84a67dc35881875bcd36615aed5e7e38e` |701| `ORIX-Docs-1.0.0.zip` | 29762912 bytes | `1957d5e30931068ae1926ba69d58639e2a975b5aae4183e7f3ca004a9df9d75e` |702703**Disk image.** Open `ORIX-Docs-1.0.0.dmg` and drag *ORIX Docs* to the *Applications* folder.704705**ZIP.** Double-click `ORIX-Docs-1.0.0.zip` and move *ORIX Docs.app* to *Applications*.706707**Verify before opening:**708709```sh710shasum -a 256 ORIX-Docs-1.0.0.dmg ORIX-Docs-1.0.0.zip711# compare with the values above, then:712spctl --assess --type execute --verbose=2 "/Applications/ORIX Docs.app"713# expected: accepted, source=Notarized Developer ID714```715716Both files are signed with a Developer ID, notarized by Apple and stapled, so Gatekeeper can verify them offline. The command-line tool is inside the bundle: `"/Applications/ORIX Docs.app/Contents/Helpers/orixdocs" --help`. Details: [distribution](docs/release/distribution.md).717718## Build Instructions719720From [`docs/development/setup.md`](docs/development/setup.md). Requirements: Xcode with the macOS SDK, [XcodeGen](https://github.com/yonaskolb/XcodeGen); network access once to fetch SwiftMath.721722```sh723# Generate the Xcode project (after any change to project.yml or to the file list)724xcodegen generate725726# Build the app (Debug into build/DerivedData)727Scripts/build.sh # or: Scripts/build.sh release728729# Build and test the engines without Xcode730cd Packages/ORIXDocsKit731swift build732swift test --no-parallel733734# Run every automated check and write docs/reports/test-results.json735Scripts/test.sh # or: Scripts/test.sh engines | app736737# Release: build, sign with the Developer ID in the keychain, embed the tool, verify738Scripts/release.sh739740# Notarize with an existing notarytool keychain profile, staple, build the DMG and ZIP,741# check with Gatekeeper, write checksums and dist/release.json742Scripts/notarize.sh743```744745`Scripts/release.sh` and `Scripts/notarize.sh` need the maintainer's Developer ID identity and notarization profile; they never create, print or change credentials ([signing](docs/release/signing.md), [notarization](docs/release/notarization.md)). Other scripts: `Scripts/coverage.sh`, `Scripts/docx-compat.sh`, `Scripts/screenshots.sh`, `Scripts/recovery-test.sh`, `Scripts/icons.sh`, `Scripts/l10n.py`.746747## Testing748749Last recorded run, from [`docs/reports/test-results.json`](docs/reports/test-results.json) (2026-11-21T03:13:10-05:00):750751| Check | Result | What it is |752|---|---|---|753| Engine tests | 582 tests in 85 suites across 10 targets: **passed**, 0 issues | Swift Testing, `swift test --no-parallel`, no window |754| Interaction self-test | 19 scenarios: **19 passed**, 0 failed | Real `NSEvent` key and mouse events sent to the document window inside the app |755| The same 19 scenarios, release record | 19 passed, 0 failed (2026-11-21T08:17:06Z) | [`docs/reports/selftest-release.json`](docs/reports/selftest-release.json), recorded for the Release build |756| Recovery | `PASS: autosaved text survived SIGKILL` | Three launches of the built app around a `kill -9` |757| XCUITest suite | **Not run** | macOS Automation Mode needs the owner's authentication, which was not given |758759Engine line coverage, from [`docs/reports/coverage.json`](docs/reports/coverage.json): **92.9 %** (26198 of 28196 lines), a lower bound of the union across test bundles; command-line tools excluded; **the application target is not included**.760761| Target | Lines | Coverage | Target | Lines | Coverage |762|---|---:|---:|---|---:|---:|763| DocAudit | 1669 | 98.4 % | DocLayout | 2479 | 86.2 % |764| DocAutomation | 1667 | 84.9 % | DocMath | 152 | 100.0 % |765| DocContainer | 327 | 100.0 % | DocModel | 3492 | 88.2 % |766| DocDOCX | 5331 | 92.2 % | DocReferences | 3204 | 93.0 % |767| DocFormats | 6297 | 97.2 % | DocReview | 1936 | 92.3 % |768| | | | DocTemplates | 1642 | 99.8 % |769770Things to know when reading these numbers ([testing](docs/development/testing.md)):771772- Tests that depend on an external tool (Poppler, pandoc, LibreOffice) return early when it is missing, and a skipped check still counts as a passed test. The report records totals, not which optional checks ran.773- The self-test synthesises events inside the process. It does not prove that the window server delivers events and does not exercise an input method, dictation, VoiceOver or drag and drop from another application.774- The tests run serially because laying out documents from many threads at once can stall in the system font registry.775- There are no unit tests in the app target.776777## Benchmarks778779Copied from [`docs/reports/benchmarks.json`](docs/reports/benchmarks.json) and [`docs/reports/benchmarks-100-pages.json`](docs/reports/benchmarks-100-pages.json). **Machine:** Apple M5 Max, 18 active cores, macOS "Version 27.0 (Build 26A5425a)". **Build:** `release`. **Tool:** `swift run -c release orixbench` on a generated report-like document (headings, body text, footnotes, 9 × 5 tables, display equations, contents, running headers). Times are milliseconds of wall-clock time for **one run**.780781| Key | 487 pages | 98 pages | Exact meaning |782|---|---:|---:|---|783| `document.words` | 177162 | 35434 | Words in the generated document |784| `document.blocks` | 1884 | 380 | Body blocks |785| `document.tables` / `footnotes` / `equations` | 80 / 320 / 80 | 16 / 64 / 16 | |786| `layout_cold_ms` | 436.577292 | 99.381666999999993 | One full layout with an empty cache, all passes included |787| `layout_passes` | 2 | 2 | Pagination passes that layout needed |788| `keystroke_model_edit_ms.median` | 0.12929099999999999 | 0.021208999999999999 | Inserting one character in the model, 200 iterations |789| `keystroke_model_edit_ms.p95` | 0.24675 | 0.029791999999999999 | |790| `keystroke_relayout_ms.median` | 14.027374999999999 | 2.287166 | The full layout that follows each insertion, warm cache |791| `keystroke_relayout_ms.p95` | 18.708082999999998 | 2.509417 | |792| `keystroke_relayout_ms.max` | 22.288083 | 2.690083 | |793| `paragraph_break_at_start_relayout_ms` | 13.884333 | 2.2699159999999998 | A paragraph break near the start plus the layout that follows |794| `find_all_ms` (`find_matches`) | 19.820166 (6480) | 3.7605 (1296) | Find all occurrences of one word |795| `numbering_ms` | 1.024208 | 0.15745799999999999 | One numbering pass |796| `pdf_export_ms` | 1395.518458 | 263.617459 | PDF export with outline and tags, including its own print layout |797| `pdf_bytes` | 3699661 | 880902 | |798| `native_save_ms` | 51.645083999999997 | 10.323708999999999 | Encoding the `.orixdoc` container in memory; no disk write |799| `native_bytes` | 137483 | 30314 | Size of that container |800| `native_open_ms` | 59.917875000000002 | 11.628083999999999 | Reading and verifying that container from memory |801| `open_and_first_layout_ms` | 452.972959 | 86.408459000000008 | `native_open_ms` plus a cold layout, timed separately and added |802| `docx_export_ms` | 454.57129099999997 | 88.359542000000005 | DOCX export, including a print layout for page references |803| `docx_bytes` | 42605 | 15815 | Size of the exported DOCX |804| `docx_import_ms` | 116.222583 | 21.128291999999998 | Importing that DOCX |805| `peak_memory_mb` | 338 | 88.5625 | Peak resident size of the whole benchmark process |806807Reading these figures ([performance](docs/development/performance.md)):808809- They are single runs of a synthetic document on one machine. They show orders of magnitude and how costs scale between two sizes; **they are not guarantees for other documents or hardware, and no unlimited page count is promised.**810- `keystroke_relayout_ms` is the layout cost of a keystroke. It does not include drawing, undo registration or statistics; end-to-end typing latency in the app is not measured.811- Not measured at all: drawing a page, scrolling, application launch, memory per document.812- Layout runs on the main thread, and every edit re-flows the whole body; incremental pagination and background layout are not implemented.813814## Privacy815816- **No account.** Nothing to sign in to.817- **No telemetry, no analytics, no crash reporting** of its own.818- **No network code.** By construction, the application and the engines contain no networking calls: the sources contain no `URLSession`, `URLRequest`, Network framework, CFNetwork or WebKit use. Two tests enforce parts of this on every run — `OnDeviceOnlyTests.noNetworkCodeInAutomationOrIntelligence` scans the automation, intelligence and inspector sources for networking, process-spawning and scripting APIs, and `OnDeviceOnlyTests.noServerBackedModelTypeInTheSources` scans all application and package sources for the server-backed model type (`Tests/DocAutomationTests/IntelligenceTests.swift`). The application requests no entitlements.819- **Documents stay on the Mac.** There is no sync, no sharing service and no real-time collaboration, by design.820- **The only way out is yours.** A ⌘-click on an `http`, `https` or `mailto` link hands that URL to the default browser or mail application; no other scheme is opened.821- **System services.** Spelling, language analysis and the on-device model are macOS services. macOS itself may download language assets for them; ORIX Docs does not initiate network requests.822823**Imported documents are treated as untrusted.** Protections, each described with its tests in [`docs/security.md`](docs/security.md):824825- ZIP limits on entry count, entry size, total size and compression ratio; ZIP64, encryption, duplicate and unsafe entry names refused;826- XML parts with a `<!DOCTYPE` or `<!ENTITY` refused; external entities never resolved; size, depth and element limits;827- macros, OLE and ActiveX never executed and never preserved; external relationships kept as text and never fetched;828- HTML and Markdown parsed by own tokenisers: no script execution, no remote fetches, images only from the source file's folder;829- LaTeX guarded before typesetting and fuzzed;830- SHA-256 integrity manifest in the native container;831- hardened runtime with no exception entitlements.832833The application is **not sandboxed**: a flaw in a parser would run with the user's file permissions ([residual risks](docs/security.md#residual-risks)).834835## Accessibility836837What exists, established by a **review of the code, not by a test with assistive-technology users** ([accessibility review](docs/reports/accessibility.md)):838839- The canvas is an accessibility text area exposing the text being edited, the selection, the insertion point, string and frame for a range, and it posts value and selection notifications.840- Controls carry accessibility labels, state as traits or values, and stable identifiers; decorative images are hidden.841- Every editor command is reachable from the main menu; 45 have a keyboard shortcut.842- Review markup uses underline, strikethrough and change bars, not colour alone.843- Images and shapes carry alternative text; the auditor reports images without it; tagged PDF figures carry it.844- Primary and secondary text tokens meet WCAG AA contrast on every surface in both appearances; tertiary text does not ([contrast table](docs/reports/accessibility.md#contrast-of-the-token-palette)).845846Gaps: **VoiceOver was not tested with a human listener**; the canvas exposes flat text without headings, links, tables or tracked changes as structure; Reduce Motion and Increase Contrast are not specifically handled; chrome text sizes are fixed. This is a review, not a certification.847848## Localization849850<div align="center">851<img src="https://git.spboucher.ai/raw/orix-docs/main/docs/screenshots/21-french-interface.png" alt="The interface in Canadian French: modes Rédaction, Mise en page, Révision, Académique, Publication, Concentration; the Révision sidebar with tracked changes; the Document inspector with Papier, Marges, Colonnes; a French research report template; comma decimal separators" width="100%">852853<sub><b>French interface.</b> Review mode in Canadian French with the French Research Report template: translated modes, sidebar, inspector and status bar, and comma decimal separators.</sub>854</div>855856The interface is available in English and Canadian French (`CFBundleLocalizations: [en, fr-CA]`). The string catalogue `App/Resources/Localizable.xcstrings` holds 1469 keys, all with a French translation; `Scripts/l10n.py build` fails when a key has none. Templates, auditor findings, generated headings ("Notes de fin") and smart quotes follow the document language.857858Known imperfection visible in the screenshot above: built-in style names such as "Body" are document data and are not translated. The French translation was not reviewed by a second person. Citation styles localise connecting terms only ([references limitations](docs/architecture/references.md#limitations)).859860## Roadmap861862An honest list of what is not done, not a promise of dates:863864- Run the XCUITest suite once Automation Mode is authorised.865- Validate exported DOCX files in Microsoft Word, Pages and Google Docs, on real-world documents.866- Run a PDF/A and PDF/UA validator; complete the tag structure (table rows and cells, lists, artifacts, document language).867- Run the Shortcuts actions from the Shortcuts app; make intent launches skip the template chooser.868- Test on an Intel Mac and on a clean second Mac.869- A VoiceOver session with a listener; structured accessibility for headings, tables and tracked changes; Reduce Motion and Increase Contrast.870- Automatic updates (Sparkle was evaluated; not implemented in 1.0.0).871- AppleScript: a minimal dictionary with an export command.872- Grammar checking and autocorrection.873- Incremental pagination and background layout; row splitting across pages; column balancing.874- A CSL processor behind the existing `CitationFormatting` seam; note-based citation styles.875- A wider LaTeX subset (`align`, `\underbrace`, `\overset`…), dependent on the math library.876- App Sandbox for the application, with the command-line tool left unsandboxed.877- Correct the French track-changes label and translate built-in style names.878- Publish the repository and the `v1.0.0` release on SPB Git, once authorised.879880## Release Status881882Version 1.0.0 (build 2), recorded on 2026-11-21. Sources: `dist/release.json` (not committed; reproduced in [`docs/release/`](docs/release/checklist.md)).883884| Step | Status | Evidence |885|---|:---:|---|886| Built (Release, universal: x86_64 + arm64, minimum macOS 15.0) | ✓ | `dist/release.json`; [`Scripts/release.sh`](Scripts/release.sh) |887| Signed: Developer ID Application: Simon-Pierre Boucher (3YM54G49SN), hardened runtime, no entitlements | ✓ | [signing](docs/release/signing.md) |888| Notarized — application: submission `5cbffb9c-d031-4702-81c6-ecb0d1068eca`, **Accepted** | ✓ | [notarization](docs/release/notarization.md) |889| Notarized — disk image: submission `794c8ee7-f0ef-491f-b7cc-7ab911771eca`, **Accepted** | ✓ | [notarization](docs/release/notarization.md) |890| Stapled (application and disk image) | ✓ | [notarization](docs/release/notarization.md) |891| Gatekeeper: `accepted`, `source=Notarized Developer ID` (application and disk image) | ✓ | `dist/release.json` |892| Checksums (SHA-256) | ✓ | Listed under [Installation](#installation) |893| Public repository on SPB Git | ✓ | [https://git.spboucher.ai/orix-docs](https://git.spboucher.ai/orix-docs), published 2026-11-21 with the owner's authorization |894| Tested on a clean second Mac | ✗ | Not done |895| SPB Git release `v1.0.0` with assets | ✓ | [https://git.spboucher.ai/orix-docs/releases](https://git.spboucher.ai/orix-docs/releases): DMG, ZIP, `SHA256SUMS.txt`, release notes; downloads re-verified (checksums match, DMG stapled, Gatekeeper accepts) |896897Published state:898899- The repository is public at [https://git.spboucher.ai/orix-docs](https://git.spboucher.ai/orix-docs) and the release assets are served from `https://git.spboucher.ai/releases/orix-docs/v1.0.0/` ([DMG](https://git.spboucher.ai/releases/orix-docs/v1.0.0/ORIX-Docs-1.0.0.dmg), [ZIP](https://git.spboucher.ai/releases/orix-docs/v1.0.0/ORIX-Docs-1.0.0.zip), [checksums](https://git.spboucher.ai/releases/orix-docs/v1.0.0/SHA256SUMS.txt)). The files were downloaded back from the forge and verified with `shasum -a 256 -c`, `stapler validate` and `spctl`.900- The rendering of this README on the SPB Git website was checked after publication: the page is served, every image path resolves and the ten Mermaid diagrams are emitted as diagram blocks. Their visual appearance in a browser was not reviewed by a person.901902Full gate-by-gate table: [release checklist](docs/release/checklist.md).903904## Known Limitations905906The consolidated list, grouped by area with a link to the detailed document for each line, is in [`docs/compatibility/limitations.md`](docs/compatibility/limitations.md). The ones that matter most before relying on ORIX Docs:907908**Verification gaps**909910- The XCUITest suite was not run; an in-app interaction self-test driving real `NSEvent`s was used instead. The two overlap but are not equivalent.911- Microsoft Word was never used to validate DOCX files; pandoc, `textutil` and LibreOffice were.912- No PDF/A or PDF/UA conformance is claimed; no validator was run.913- The Shortcuts actions were compiled but never run from Shortcuts.914- VoiceOver was not tested with a human listener; the accessibility statement is a review by code inspection.915- Intel is built but untested; no clean second Mac was used.916917**Not implemented in 1.0.0**918919- AppleScript support (deferred).920- Automatic updates (Sparkle evaluated, not implemented).921- Grammar checking and autocorrection.922- Real-time collaboration — intentionally absent.923- Specific handling of Reduce Motion and Increase Contrast.924- App Sandbox.925926**Behaviour to know**927928- Layout from many threads at once can stall in the system font registry: tests run serially and batch jobs bound their concurrency.929- The on-device model's "concise tone" action often returns the text unchanged, reported as no edit proposed.930- Table rows and footnotes do not split across pages; columns are not balanced ([pagination limits](docs/architecture/pagination.md#limits)).931- Track changes does not cover table structure, paragraph formatting or styles ([text engine](docs/architecture/text-engine.md#5-editing-operations)).932- Six built-in citation styles, not a CSL processor ([references](docs/architecture/references.md#limitations)).933- Equations are a subset of LaTeX math ([technology evaluation, section 6](docs/research/technology-evaluation.md#6-math)).934- Other formats lose what they cannot carry — see the table in [format compatibility](docs/compatibility/formats.md#summary).935936## ORIX Ecosystem937938ORIX Docs is the macOS member of a family of applications that share the ORIX plate, ring and accent-pair identity ([brand guidelines](docs/design/brand-guidelines.md)). Its siblings, for iOS and iPadOS, are on SPB Git:939940| Application | Platform | Repository |941|---|---|---|942| ORIX Scan | iOS / iPadOS | <https://git.spboucher.ai/orix-scan> |943| ORIX Calc | iOS / iPadOS | <https://git.spboucher.ai/orix-calc> |944| ORIX Audio | iOS / iPadOS | <https://git.spboucher.ai/orix-audio> |945946## License947948© 2026 Simon-Pierre Boucher. All rights reserved.949950**Third-party notices**951952- **SwiftMath** — <https://github.com/mgriebling/SwiftMath>, pinned at revision `0b0222e102ba415b352cd29f334075622bd4e6aa`. MIT License, Copyright (c) 2023 Computer Inspirations.953- **Math fonts bundled with SwiftMath** (`mathFonts.bundle`, shipped inside the application's resources): distributed under the GUST Font License and the SIL Open Font License; both licence texts are in the bundle (`GUST-FONT-LICENSE.txt`, `OFL.txt`). SwiftMath's README names the licence for Latin Modern Math, TeX Gyre Termes Math (GUST), XITS Math and KpMath (OFL); the bundle does not document the licence of each of the other fonts individually, a point the [technology evaluation](docs/research/technology-evaluation.md#6-math) records as not verified.954955Contact: contact@spboucher.ai956