smnandre · Sep 19, 2026 · Sep 19, 2026
diff --git a/README.md b/README.md
@@ -71,7 +71,7 @@ $label = Markdown::github()->toInlineHtml('Install **Alto**');
 ```
 
 See [Installation](docs/installation.md), [HTML](docs/conversion/html.md),
-[Profiles](docs/documents/profiles.md), and [Security](docs/engine/security.md) to choose the
+[Profiles](docs/documents/profiles.md), and [Security](docs/security.md) to choose the
 right language and HTML policy.
 
 ## Open a document when you need more
@@ -118,7 +118,7 @@ if ($file->hasChanges()) {
 ```
 
 Source ranges use original byte offsets. `toMarkdown()` preserves unchanged
-bytes, line endings, and a UTF-8 BOM. Alto rejects an edit when it cannot apply
+bytes, line endings, and a UTF-8 BOM. ALTO rejects an edit when it cannot apply
 it safely under the documented V1 contract.
 
 The documentation covers this in more depth: [Queries](docs/documents/queries.md)
@@ -133,15 +133,26 @@ to enforce content and style policies.
 Trusted extensions add custom blocks, leaf inlines, native and link-aware HTML
 decoration, document render projections, lint, formatting, metrics,
 heading-level projection, permalinks, and generated tables of contents through
-compiled contracts. Read [Extensions](docs/extensions/index.md) and
+compiled contracts. Read [Extensions](docs/extensions.md) and
 [Compatibility](docs/extensions/compatibility.md) for the extension contracts
-and migration notes from historical Alto CommonMark extensions.
+and migration notes from historical ALTO CommonMark extensions.
 
 ## Documentation
 
-- [Documentation index](docs/index.md): browse the complete guide set.
-- [API reference](docs/api/index.md) and [Exceptions](docs/api/exceptions.md): the
-  public surface and recovery contracts.
+- [Installation](docs/installation.md): install the package and verify the runtime.
+- [Getting started](docs/getting-started.md): render and inspect a document.
+- [Conversion](docs/conversion.md): produce HTML or Markdown output.
+- [Documents](docs/documents.md): query, measure, and edit source-backed content.
+- [Quality](docs/quality.md): lint, fix, and format Markdown.
+- [Extensions](docs/extensions.md): choose bundled capabilities or create one.
+- [Syntax](docs/syntax.md): add authoring syntax.
+- [Rendering](docs/rendering.md): control document and HTML output.
+- [Resources](docs/resources.md): resolve imported, included, and embedded content.
+- [Security](docs/security.md): define HTML, input, and resource boundaries.
+- [Errors](docs/errors.md): recover from parse, edit, resource, and file failures.
+- [Performance](docs/performance.md): select and measure the processing path.
+- [Compliance](docs/compliance.md): review supported Markdown specifications.
+- [Documentation index](docs/index.md): browse every guide.
 
 ## Contributing
 

diff --git a/docs/api/documents.md b/docs/api/documents.md
diff --git a/docs/api/editing.md b/docs/api/editing.md
diff --git a/docs/api/extensions.md b/docs/api/extensions.md
diff --git a/docs/api/index.md b/docs/api/index.md
diff --git a/docs/api/queries.md b/docs/api/queries.md
diff --git a/docs/engine/compliance.md → docs/compliance.md b/docs/engine/compliance.md → docs/compliance.md
@@ -25,7 +25,7 @@ The published package carries the conformance fixtures and runs them with the
 rest of the suite:
 
 ```bash
-composer tests
+composer test
 ```
 
 The full quality gate also runs static analysis and style checks on top of the

diff --git a/docs/conversion.md b/docs/conversion.md
@@ -0,0 +1,21 @@
+# Conversion
+
+Convert Markdown directly when the application only needs one output. Open a
+document first when the same parsed structure will also be queried, edited,
+linted, or rendered more than once.
+
+```php
+use Alto\Markdown\Markdown;
+
+$html = Markdown::github()->toHtml("# Guide\n\nRead **carefully**.\n");
+```
+
+## Output
+
+- [HTML](conversion/html.md): render blocks or inline fragments with an explicit
+  HTML policy.
+- [Markdown](conversion/markdown.md): preserve original source or produce
+  normalized Markdown.
+
+Direct conversion avoids retaining a document object. Document output preserves
+unchanged source bytes until an operation explicitly normalizes them.
diff --git a/docs/conversion/html.md b/docs/conversion/html.md
@@ -46,5 +46,5 @@ The default policy escapes raw HTML and filters unsafe URL schemes. Pass a
 `RenderOptions` value only when the application has an explicit reason to use
 another policy.
 
-Read [Security](../engine/security.md) before enabling authored HTML. Continue
+Read [Security](../security.md) before enabling authored HTML. Continue
 with [Markdown](markdown.md) when output must remain Markdown.
diff --git a/docs/documents.md b/docs/documents.md
@@ -0,0 +1,40 @@
+# Documents
+
+A document retains the parsed model and original source. Use it when an
+application needs to inspect, reuse, measure, or change Markdown without
+rewriting unrelated content.
+
+```php
+use Alto\Markdown\Markdown;
+
+$document = Markdown::github()->fromString("# Guide\n\nRead the docs.\n");
+$title = $document->title()?->text();
+```
+
+`$title` is `Guide`.
+
+## Guides
+
+- [Profiles](documents/profiles.md): choose CommonMark, GFM, or GitHub syntax.
+- [Queries](documents/queries.md): find headings, sections, links, and code.
+- [Statistics](documents/statistics.md): compute an immutable document summary.
+- [Editing](documents/editing.md): make source-preserving changes and save files.
+- [Nodes](documents/nodes.md): inspect and mutate typed handles.
+
+## Entry points
+
+| Method | Return | Purpose |
+| --- | --- | --- |
+| `profile()` | `Profile` | Return the compiled language profile. |
+| `with(ExtensionInterface ...$extensions)` | `self` | Return a factory with trusted extensions. |
+| `fromString(string $source, ?ParseOptions $options = null)` | `MarkdownDocument` | Parse an in-memory document. |
+| `open(string $path, ?ParseOptions $options = null)` | `MarkdownFile` | Read and parse a file. |
+| `toHtml(...)` | `string` | Render block Markdown directly. |
+| `toInlineHtml(...)` | `string` | Render an inline fragment directly. |
+| `builder()` | `MarkdownBuilder` | Start a document builder. |
+| `fragment()` | `MarkdownFragmentBuilder` | Start a fragment builder. |
+
+`MarkdownDocument` exposes typed accessors, `query()`, `ensure()`, `lint()`,
+`fix()`, `format()`, `stats()`, `toMarkdown()`, and `toHtml()`.
+`MarkdownFile` adds `path()`, `save()`, and `saveAs()`. See
+[Errors](errors.md) for recoverable parse, edit, resource, and file failures.
diff --git a/docs/documents/editing.md b/docs/documents/editing.md
@@ -27,6 +27,7 @@ The result changes only the section body:
 ## Install
 
 Run Composer.
+
 ```
 
 Available typed edits:
@@ -218,6 +219,10 @@ Compare-before-write protects against silently replacing bytes changed by
 another editor or process. It is optimistic conflict detection, not a
 filesystem lock.
 
+After a conflict, keep the pending diff for review, reopen the current file,
+and reapply the intended change against its updated content. Do not disable
+comparison merely to force a stale write over another editor's changes.
+
 Protected `saveAs()` can create a new target but refuses to replace an existing
 file that this document did not open. The default comparison option remains
 `false`, so enable it explicitly when concurrent changes are possible.
@@ -252,5 +257,5 @@ mode handling is platform-limited. Use `atomic: false` only when retaining the
 existing inode and its metadata is more important than all-or-nothing
 replacement. A non-atomic write can leave partial content after an I/O failure.
 
-See [Exceptions](../api/exceptions.md) for conflicts, stale handles, missing sections, and
+See [Errors](../errors.md) for conflicts, stale handles, missing sections, and
 unsupported edits.
diff --git a/docs/api/nodes.md → docs/documents/nodes.md b/docs/api/nodes.md → docs/documents/nodes.md
@@ -1,4 +1,4 @@
-# Nodes API
+# Nodes
 
 Typed handles expose semantic values and the mutations Alto can lower safely
 to source patches.
@@ -27,4 +27,4 @@ query the current document again.
 
 Generic block movement and insertion accept only direct children of the
 document root. Typed mutations retain their own documented boundaries. See
-[Editing](../documents/editing.md) for worked operations.
+[Editing](editing.md) for worked operations.
diff --git a/docs/api/exceptions.md → docs/errors.md b/docs/api/exceptions.md → docs/errors.md
@@ -63,7 +63,7 @@ Use the precise subtype when its recovery is different:
 Parser limit subclasses expose the configured and attempted values. File
 exceptions expose the original application path through `path`. Resource limits
 and their exact counting rules are documented in
-[Security](../engine/security.md#bound-parsing-and-file-access).
+[Security](security.md#bound-parsing-and-file-access).
 
 Unknown generic node kinds also raise an Alto domain exception. Construct
 factories with custom extensions during application startup rather than after
@@ -122,5 +122,5 @@ own symlink policy. Existing non-regular targets are rejected. A relative path
 is anchored to its canonical parent when opened or adopted by `saveAs()`, but
 that does not replace application authorization. Permission inspection or
 restoration failures abort atomic replacement and preserve the pending diff.
-See [Editing](../documents/editing.md#preview-and-save) for the complete
+See [Editing](documents/editing.md#preview-and-save) for the complete
 persistence contract.