English manuals, architecture explanations, extension guides, and API reference for InnoEngine.
Read the documentation · Contribute · Publication guide · API authoring guide
InnoEngine.Docs explains how to use and extend the engine. It owns the English Manual, tutorials, architecture explanations, authored API explanations, navigation, and static website. It is also the content source for the engine's local documentation queries: the website and AI readers use the same page and symbol relationships.
| Information | Authoritative location |
|---|---|
| Engine behavior, C# declarations and XML comments | InnoEngine source |
| API extraction, script projection and documentation query tooling | InnoEngine tooling |
| Manual, tutorials, architecture and API explanations | content/en/ in this repository |
| Captured API facts, project metadata and engine version binding | reference/ in this repository |
| Website layout, shared navigation and browser search | This repository's site implementation |
| Development rules and task workflows | Each repository's AGENTS.md and .agents/ |
Product documentation describes capabilities and contracts; it does not replace repository development rules or historical acceptance records. The API version is recorded in engine.lock.json. Publishing a documentation correction does not require updating to the newest engine commit.
InnoEngine feature branch
→ maintain C# declarations and XML; perform applicable engine checks
→ human merges the engine PR into master
→ independent API export verifies the complete selected reference set
→ protected synchronization updates InnoEngine.Docs/draft when content changes
↑
Manual/tutorial changes enter through a PR into draft
↓
Docs validation and preview artifacts
↓
human opens a draft → main PR
↓
required documentation checks pass
↓
human merges using a merge commit
↓
main validates or reuses matching successful evidence
↓
GitHub Pages deploys the exact verified site artifact
API synchronization updates documentation inputs; it does not publish the website. Neither workflow automatically creates or merges the release PR. Docs publication does not wait for unrelated full-engine CI matrices and does not certify engine functionality.
- Maintain XML for changed public contracts in the engine repository. After a human master merge, the API workflow exports real C# facts and actual script projections, then synchronizes changed content to Docs
draft. - Internal changes with unchanged API/XML/projection content do not require a new Docs commit. Ordinary commits, pushes and session restarts do not each require a documentation release.
- If the user's workflow changes, update the affected Manual or tutorial separately in a Docs branch based on
draft. API export cannot write those tutorials for you. - Export or synchronization failures leave the existing documentation snapshot and published site intact. Inspect the engine's Export documentation API workflow separately from the Docs workflow.
Engine API includes public and externally usable protected C# contracts owned by src/ and build/, excluding tests and fixtures. Tooling, entry points, concrete platform implementations, backends, extern and non-C# APIs are outside this reference. Scripting API uses actual projected declarations, organized by Runtime, Editor and Authoring Scope. Engine API navigation follows actual project segments.
Create a feature branch from draft, change the relevant content, and open a PR into draft. Manual, architecture and tutorial pages are maintained here independently of API synchronization.
Every API type and member has its own explanation and stable symbol identity:
| API prose marker | Synchronization behavior |
|---|---|
source: xml, or no marker in a registered API file |
Refreshes the explanation from source XML; removes the generated file when the API is removed |
source: <author name> |
Preserves authored prose while source declarations and relationships continue to update |
| Unknown marker | Fails rather than guessing ownership |
Set source to your name before taking over an API explanation. Preserve its uid and symbol. A change to a source contract can mark the preserved explanation Outdated. Removed APIs with manual prose retain their files for review outside current navigation and default search. These rules never authorize overwriting ordinary Manual pages. See the API authoring guide for frontmatter, stable addresses and review identities.
- Open a
draft → mainPR when the documentation is ready to publish. Multiple documentation updates may be released together. - If GitHub requires Update branch, merge main's ancestry into draft and resolve any real conflicts. Do not force-push or reset draft.
- Wait for required Documentation validation. API editorial reminders are advisory.
- Merge manually using Create a merge commit. Keep the persistent
draftbranch; Synchronize draft then fast-forwards it to main without creating a commit. - In Actions → Documentation, open the main push run. Confirm both validation and Deploy GitHub Pages succeed.
- Open the published site, check an API deep link and search, and confirm the expected API version. A merged PR alone does not prove deployment succeeded.
GitHub Pages is the sole publisher. One verified Pages archive serves as both preview and delivery artifact; deployment does not rebuild the website or upload a second copy. Failed publication retains the previous successful site. Setup and recovery instructions live in the publication guide.
| Event | Expected behavior |
|---|---|
| Feature branch push without a PR | No automatic Docs workflow; local work remains available |
| PR into draft | Incremental affected-page checks and explicitly partial preview; no deployment |
| PR from draft into main | Full actual merge-candidate website, Pagefind and release checks; one publication artifact |
| Draft push, including API synchronization | Incremental checks; an open release PR can cover the same input only after its required checks pass |
| Main push after a human merge | Validate or reuse matching evidence, then deploy through Pages |
| Manual run | Select Incremental diagnosis or Release validation; only a Release on main can publish |
| Merge-group check | Validate the candidate; do not publish |
Documentation validation is the required aggregate. It reconciles evidence selection, Windows projection and Linux preparation; missing, canceled or failed prerequisites cannot silently pass. Checks cover content and API integrity, links, examples, rendering and browser journeys.
API editorial coverage reports missing, unchanged-default or stale manual explanations. A neutral result is a non-blocking reminder, not a failed deployment and not proof of semantic completeness. Failure of the reporting tool itself is a real fault.
Documentation projection follows one execution plan. Ordinary edits render changed pages, direct incoming references, required contracts, category and pagination context. Shared styles use representative page kinds and selected browser journeys. Search changes and Release mode generate the complete search index. Instructions, records and README changes run operational structure/link checks without a website build.
Independent page and example receipts bind their actual content, dependencies and tool inputs. A changed engine commit alone does not rebuild an identical managed documentation bundle. Frozen canonical data is reused throughout the job. Unknown relationships expand conservatively with reasons; missing checks and altered authenticated evidence fail.
A Release uses every page and the full reading suite. Same-repository PR artifacts can be promoted only when their control code matches trusted main. A PR changing builders, checks or publication code is checked before merge and checked once again on main. The deployment job never executes candidate scripts or rebuilds the site. Linux preparation has its own input-bound receipt. Partial previews list included pages, expire after 7 days and are explicitly rejected by the publisher; release artifacts last 90 days and diagnostics 30 days.
The plan and result are retained under artifacts/ci/. Their statuses distinguish Passed, Reused, Failed, Blocked and NotApplicable. Receipts preserve the original producer and do not turn a pending run into a pass.
Deploy GitHub Pages is intentionally skipped on PRs and draft. On main, a skip caused by failed validation means nothing was published and requires investigation. Check the run's branch and event before interpreting a skipped job. Push and PR checks may appear together on the same commit; the PR preview and main publication serve different purposes.
Diagnostics are retained for 30 days; site artifacts and reusable evidence for 90 days. Versioned content, captured API facts and pinned tools allow rebuilding after artifacts expire.
| Operation | Authorization |
|---|---|
| Engine export → Docs draft | Restricted GitHub App installation token with Docs Contents write |
| Documentation validation | Repository-scoped GitHub Actions token |
| Main → draft fast-forward | Repository-scoped GitHub Actions token with Contents write; pushes only draft, never forces |
| Editorial report | Protected reporting workflow with Checks write |
| GitHub Pages publication | Deploy job's Pages write permission and short-lived OIDC identity; main-only environment |
| Release decision | Human merge into main |
The synchronization App's private key stays in the engine's Actions secret. GitHub Pages does not use that private key or require a separate hosting token. No external hosting integration should remain connected to these repositories. A historical external deployment status on an older commit is not a Docs workflow failure and must not be replaced with a fabricated success.
Use the repository's pinned tool versions and lockfile:
npm ci
npm run build
npm run previewThe build explicitly prepares the pinned managed documentation tool when needed; it does not prepare Native dependencies or engine products. Read CONTRIBUTING.md for focused authoring and browser checks.
AI queries use the engine's existing Build docs command group. Select an explicit Docs checkout or prepared snapshot, prepare it with docs index, then use docs search, docs read or docs symbol. Reading a prepared snapshot does not compile, evaluate SDK projects or access the network. Snapshot freshness and source-API verification are separate states; refresh after relevant content changes rather than reindexing for every read.
Documentation follows the engine's Apache-2.0 license unless an individual asset states otherwise. InnoEngine branding retains its separate license and attribution.
Engine project guides use the same editorial ownership policy as API explanations. The linked Engine project guides row opens the index, and its square toggle reveals the flat list of project pages. Their registration is maintained in reference/projects/content.json.
-
Synchronization follows the API page policy for additions and removals. A new engine project that no project page owns receives a registered Synced guide:
tests/projects undercontributing/testing/projects/,backends/projects underbackends/projects/, all others underarchitecture/projects/. When a project is removed, its Synced guide is deleted and an Authored guide is kept with an editorial warning. -
A project page that is not in the registry is hand-authored. Synchronization never registers, rewrites or deletes it.
-
Generated metadata:
uid,symbol,title,kind,owners,sourceFingerprint, optionaloutdatedFor, andcontracts. Do not edit these fields to change source facts. -
Authoring metadata:
source,description,outdated, and optional aliases.source: xml(or an absent source field in a registered guide) permits synchronization to regenerate the body from the selected project source/XML facts. A nonempty author name protects the body. -
description: nullleaves the default description to the source/content pipeline. A nonempty list supplies the project introduction and the Purpose text in category tables. For example,description: ["Select audio providers for a host composition."]changes the Audio category explanation without editing a generated category page. -
Synced pages use source XML. Set
sourceto a human or AI author and commit the Markdown to show Authored. When source facts change, synchronization preserves that text and displays Outdated. Editing the body or description restores Authored on the next build. A later source change can mark it Outdated again. An explicitly setoutdated: truelasts until the author clears it. -
The same three states apply to registered project guides and API pages. The generated fingerprints ignore XML line endings and source coordinates. Editing and committing the page is the entire authoring workflow.
Unregistered Manual and tutorial pages are outside this mechanism.