Add generated public documentation inventories

[ahmelkholy]

Integrates the complete commit history of #2 after #1, retaining the evidence-aligned model/solver/troubleshooting manuals while adding generated study/model/parser/case inventories, a public professional workflow, and result-validation guidance. The check now generates four inventories, audits 67 model owners, 15 parser owners, 15 required pages, 102 cases, eight templates, private-path leakage, links, and public Engine load before Documenter builds. Removed the branch completion-status artifact and personal/private workspace instructions. Local verification: docs checks PASS; Documenter build PASS; Resources repository/licence/privacy contracts 75/75; report templates 3/3.

[Copilot]

Pull request overview

Adds generated public documentation inventories and expands guidance for studies, workflows, parsing, and result validation.

Changes:

• Adds workflow, validation, study, glossary, and deck/card documentation.
• Generates study, model, parser, and case inventories.
• Integrates generation and audits into documentation checks and excludes generated artifacts.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Summary	Final review comments
docs/src/study-reference.md	Study maturity and capability guidance	2 nit comments (2 votes each): align the not_implemented contract with implementation behavior; demote section headings to H2.
docs/src/results-and-validation.md	Result interpretation and validation guidance	Nit (2 votes): demote section headings to H2.
docs/src/professional-workflow.md	Reproducible engineering workflow	Moderate (2 votes): include the required AIMORAProject checkout or update the package-test command.
docs/src/glossary.md	Expanded technical terminology	Nit (2 votes): retain definitions for existing concepts still used throughout the documentation.
docs/src/deck-card-reference.md	Deck and parser guidance	Nit (2 votes): demote section headings to H2.
docs/make.jl	Documentation navigation and build entrypoint	Critical (1 vote): generate required inventories before makedocs so direct Documenter invocations work from a fresh checkout.
docs/generate_reference_pages.jl	Generated public inventories	Moderate (3 votes): fail when required model/parser source roots are missing or invalid instead of generating empty inventories.
docs/content_audit.jl	Documentation completeness audits	No final comments.
docs/check.jl	Integrated documentation checks	No final comments.
.gitignore	Generated artifact exclusions	No final comments.

Suppressed comments (5)

docs/check.jl:71

• The new recursive scan includes generated inventories, but its forbidden set still checks only /home/ and does not include the /Users/, /mnt/, /tmp/, or private attachment patterns used by the existing content gate. The case catalog copies catalog-controlled paths and descriptions into these generated pages, so those values can bypass the claimed private-path audit and be published. Apply the same path/URL checks to every page scanned here.

    sort(collect(Iterators.flatten(
        (joinpath(root, name) for name in names if endswith(name, ".md"))
        for (root, _, names) in walkdir(joinpath(REPOSITORY_ROOT, "src"))
    )))

docs/generate_reference_pages.jl:46

• @enum also supports inline members such as @enum State idle running; this branch only scans subsequent lines. For that valid form it can omit the members and continue scanning until a later end, misclassifying unrelated identifier-only lines as enum members, so the generated declaration inventory is incorrect. Parse inline members and stop scanning when the declaration is complete.

        if kind == :enum
            enum_match = match(r"^([A-Za-z_][A-Za-z0-9_]*)\s*(?:=\s*[-+0-9]+)?\s*,?$", stripped)
            enum_match === nothing || push!(values, enum_match.captures[1])
            continue

docs/generate_reference_pages.jl:232

• The generated execution meaning repeats the typed-result promise for planned studies, but the current engine's study_not_implemented helper raises instead of returning a result. This makes the generated catalog document an API that callers cannot use; align the generated wording with the engine or change the engine contract.

function _status_meaning(status)
    status == :implemented && return "Callable and expected to produce a typed result for valid supported input."
    status == :prototype && return "Experimental interface; behavior and qualification may change."
    status == :legacy_reference && return "Retained for comparison or historical qualification, not the production execution path."
    return "Declared roadmap interface only; callers must expect a not-implemented result."

docs/src/professional-workflow.md:57

• This repeats a typed-return contract that the current public API does not implement: planned run_* functions call study_not_implemented, which throws rather than returning StudyResult(status = :not_implemented). Please align this workflow with the actual failure behavior or update the engine contract before presenting it as the user-facing procedure.

A planned descriptor must return a transparent `not_implemented` result. It must never fabricate values or silently substitute another study.

docs/src/results-and-validation.md:109

• This residual omits the initial stored-energy term, even though the preceding text requires recording it. For a lossless case initialized with capacitor/inductor/machine energy, the expression is nonzero solely because that initial energy is missing; include E_{\text{stored}}(0) (or define every energy term as a change from the integration start).

r_E(t) = E_{\text{external}}(t) - E_{\text{stored}}(t) - E_{\text{dissipated}}(t) - E_{\text{exported}}(t).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.