Integrate main command changes with buopt schemas

Add cmd survey
stash docs
2026-09-29 17:58:27 -04:00 · 2026-09-29 17:12:23 -04:00 · 2026-09-29 17:12:23 -04:00 · 2026-09-29 17:12:23 -04:00 · 2026-09-28 08:46:34 -04:00 · 2026-09-25 17:31:09 -04:00
810 changed files with 105675 additions and 28356 deletions
@@ -231,7 +231,7 @@ set(CMAKE_FIND_USE_PACKAGE_REGISTRY FALSE)
 # Prepare to manage and build BRL-CAD's external dependencies. Specifies a
 # specific commit hash to use in the 'bext' repository.
 include(BRLCAD_ExternalDeps)
-brlcad_bext_init(12115e6c5922e2db27a9b88e00dd714af5315f69)
+brlcad_bext_init(0682795bcfe34644c17e5a4bdd0225c76f6bdc98)

 #---------------------------------------------------------------------
 # Define various utilities.
@@ -678,8 +678,13 @@ endif(MSVC)
 # before use so platforms without GNU/LLVM-style linker options are skipped.
 brlcad_check_linker_flag(C "LINKER:--no-undefined" BRLCAD_LINKER_NO_UNDEFINED_C_FLAG_FOUND)
 brlcad_check_linker_flag(CXX "LINKER:--no-undefined" BRLCAD_LINKER_NO_UNDEFINED_CXX_FLAG_FOUND)
-if(BRLCAD_LINKER_NO_UNDEFINED_C_FLAG_FOUND AND BRLCAD_LINKER_NO_UNDEFINED_CXX_FLAG_FOUND)
+if(BRLCAD_LINKER_NO_UNDEFINED_C_FLAG_FOUND AND BRLCAD_LINKER_NO_UNDEFINED_CXX_FLAG_FOUND
+   AND NOT BRLCAD_ENABLE_ADDRESS_SANITIZER)
  set(BRLCAD_LINKER_NO_UNDEFINED_FLAG "LINKER:--no-undefined" CACHE STRING "Linker flag requiring resolved shared library symbols" FORCE)
+else()
+  # Clang links the AddressSanitizer runtime into executables, leaving its
+  # shared-library instrumentation symbols unresolved until then.
+  set(BRLCAD_LINKER_NO_UNDEFINED_FLAG "" CACHE STRING "Linker flag requiring resolved shared library symbols" FORCE)
 endif()
 brlcad_check_linker_flags(C BRLCAD_LINKER_WHOLE_ARCHIVE_GROUP_C_FLAG_FOUND "LINKER:--whole-archive" "LINKER:--no-whole-archive")
 brlcad_check_linker_flags(CXX BRLCAD_LINKER_WHOLE_ARCHIVE_GROUP_CXX_FLAG_FOUND "LINKER:--whole-archive" "LINKER:--no-whole-archive")
@@ -1642,21 +1647,31 @@ if(NOT MSVC)
  endif(BRLCAD_WARNINGS OR BRLCAD_ENABLE_STRICT)

  if(BRLCAD_ENABLE_COVERAGE)
-    # TODO: These seem to GCC specific flags - should probably set up for clang
-    # as well if that's our compiler...
-    # https://clang.llvm.org/docs/SourceBasedCodeCoverage.html
-    # If we need different settings for different tools, should
-    # encapsulate each tool's setup in a function
-    check_c_flag(ftest-coverage)
-    check_cxx_flag(ftest-coverage)
-    if(FTEST_COVERAGE_C_FLAG_FOUND)
-      set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -ftest-coverage -fprofile-arcs -fprofile-update=atomic")
-      set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -ftest-coverage -fprofile-arcs -fprofile-update=atomic")
-      set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -lgcov -ftest-coverage -fprofile-arcs -fprofile-update=atomic")
-      set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -lgcov -ftest-coverage -fprofile-arcs -fprofile-update=atomic")
-    else(FTEST_COVERAGE_C_FLAG_FOUND)
-      message(SEND_ERROR "Building with coverage is not supported by BRL-CAD on this platform.")
-    endif(FTEST_COVERAGE_C_FLAG_FOUND)
+    if(CMAKE_C_COMPILER_ID MATCHES "Clang" AND CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+      check_c_flag(fprofile-instr-generate)
+      check_cxx_flag(fprofile-instr-generate)
+      check_c_flag(fcoverage-mapping)
+      check_cxx_flag(fcoverage-mapping)
+      if(NOT FPROFILE_INSTR_GENERATE_C_FLAG_FOUND OR
+         NOT FPROFILE_INSTR_GENERATE_CXX_FLAG_FOUND OR
+         NOT FCOVERAGE_MAPPING_C_FLAG_FOUND OR
+         NOT FCOVERAGE_MAPPING_CXX_FLAG_FOUND)
+        message(FATAL_ERROR "Clang source-based coverage is not supported by this toolchain.")
+      endif()
+      add_compile_options(-fprofile-instr-generate -fcoverage-mapping)
+      add_link_options(-fprofile-instr-generate)
+    else()
+      check_c_flag(ftest-coverage)
+      check_cxx_flag(ftest-coverage)
+      if(FTEST_COVERAGE_C_FLAG_FOUND AND FTEST_COVERAGE_CXX_FLAG_FOUND)
+        set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -ftest-coverage -fprofile-arcs -fprofile-update=atomic")
+        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -ftest-coverage -fprofile-arcs -fprofile-update=atomic")
+        set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -lgcov -ftest-coverage -fprofile-arcs -fprofile-update=atomic")
+        set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -lgcov -ftest-coverage -fprofile-arcs -fprofile-update=atomic")
+      else()
+        message(FATAL_ERROR "GCC coverage is not supported by this toolchain.")
+      endif()
+    endif()
  endif(BRLCAD_ENABLE_COVERAGE)

  if(BRLCAD_ENABLE_STRICT)
@@ -13,6 +13,8 @@ changes made.  See document footer for additional details.
 --- 20XX-XX-XX  Release 7.46.0                                     ---
 ----------------------------------------------------------------------

+* improved pixscale & bwscale scaling and image piping - Sean Morrison
+* restored pixdiff behavior on .pix, added -b for .bw - Sean Morrison
 * updated MGED and Archer for Tcl 8.6.18 and Itcl/Itk 4 - Cliff Yapp
 * fixed writes to fileless geometry databases - Cliff Yapp
 * fixed nastran-g handling of large property IDs - Rupesh, Cliff Yapp
@@ -212,6 +214,9 @@ and extensively improving existing docs.
 	- Cliff Yapp, Sean Morrison
 * fixed gqa exactly symmetric volumetric estimates - Sean Morrison
 * added support to rtedge for perspective renderings - Sean Morrison
+* added bu_cmd_schema for full command grammars, completion, and validation;
+  bu_opt remains the concise supported option-only API over the same engine
+  - BRL-CAD
 * rt -l8 rendering time heat graphs - Stephen Kennedy, Sean Morrison
 * added 'icv anim' for APNG and MJPEG animation files - Clifford Yapp
 * added BREP/NURBS import support to gcv x3d importer - Sean Morrison
@@ -0,0 +1,630 @@
+buopt production-readiness checklist
+====================================
+
+This checklist records the issues found during the post-rebase review of the
+buopt branch.  An item is complete only when the implementation and relevant
+tests are both in place.
+
+[x] Make libged command schema/grammar registries safe during static
+    initialization and concurrent registration/lookup.
+[x] Make semantic-provider initialization and access thread-safe.
+[x] Separate semantic candidate values from command-line insertion encoding
+    and transient-display escaping.  Cover whitespace, quoting characters,
+    Tcl metacharacters, newlines, and terminal control bytes.
+[x] Add schema-selectable database-object completion filters.  Ordinary
+    geometry roles should exclude _GLOBAL; metadata-aware and binary-object
+    commands should explicitly request the broader or specialized sets they
+    support.
+[x] Make a bare Escape cancel gsh completion without blocking for subsequent
+    input bytes.
+[x] Honor the completion layout API's character-cell contract for UTF-8,
+    including wide and combining characters.
+[x] Make MGED terminal cursor positioning safe for wrapped input, and account
+    for wrapped input rows in the Tk one-third-prior-output policy.
+[x] Repaint gsh transient completion displays when a Windows console resize
+    event is received.
+[x] Define and enforce safe initialization/lifetime contracts for public
+    completion and validation result objects.
+[x] Allow qged/libqtcad command completion at an empty prompt.
+[x] Reject negative argc in bu_cmd_schema_parse_complete before size_t casts.
+[x] Audit and either eliminate or explicitly constrain libged unbound schema
+    rows so execution and completion grammars cannot silently drift.
+[x] Pass BRL-CAD's repository regression: portable string/file APIs,
+    bu_setprogname in test mains, required source headers, and editor footers.
+[x] Keep public libbu schema declarations C-only; do not expose C++
+    constructors in public C data structures.
+[x] Preserve attached short-option arguments (for example, draw -m3) across
+    native parsing, validation, option-presence checks, operand counting, and
+    option-span analysis.
+[x] Preserve draw's established transparency and line-width defaults when
+    native options are absent.
+[x] Update the GQA plotting test for canonical encoded display-list paths.
+[x] Keep non-command database-attribute readers on the supported bu_opt API
+    and limit the native-schema source audit to actual command parsers.
+[x] Keep independently launched fbserv stress suites from racing for
+    overlapping ports while preserving simultaneous worker/server startup;
+    report closed-peer writes as failures instead of terminating on SIGPIPE.
+[x] Correct MGED's appended Configure binding so GUI initialization does not
+    execute a stray closing brace, and exercise GUI binding installation in a
+    display-independent Tcl regression test.
+[x] Remove the quadratic candidate-validation path from empty database-object
+    completion, keep option spellings out of object listings, recognize an
+    editable `--` as a long-option prefix, and avoid sorting every possible
+    summary refinement during large completion layouts.
+[x] Add regression coverage for all corrected behavior and run the full build,
+    bu_opt compatibility tests, schema/completion tests, frontend PTY tests,
+    available Qt tests, and regress-repository.
+[x] Keep bu_opt as the approachable option-authoring API while exposing
+    side-effect-free completion and validation inferred from every standard
+    bu_opt reader.
+[x] Add an ABI-safe per-option sidecar for aliases, custom value types,
+    candidates, hints, variable token counts, and context-aware validators.
+[x] Add a reentrant builder macro so commands declare familiar option rows
+    once and use them for parsing, help, completion, and schema publication.
+[x] Add a compact GED option specification for positional roles and command
+    constraints, retaining full native schemas and parser-owned grammars only
+    for cases that need their additional expressiveness.
+[x] Convert representative ordinary, constrained, and context-sensitive GED
+    commands (bb, kill, and ls) to the compact facade and preserve hidden,
+    type-filtered, alias, and _GLOBAL completion behavior.
+[x] Add and registration-time lint a compact positional DSL for ordinary
+    option specifications.  Cover cardinalities, GED semantic providers,
+    inline keyword vocabularies, inclusive numeric domains, common positive
+    and nonnegative domains, and standard color/vector/pattern token shapes.
+[x] Survey the remaining full schemas for repeated declarative patterns.
+    Keep keyword metadata with aliases/descriptions, command-specific
+    validation, heterogeneous repeated groups, subcommand trees, and
+    parser-owned languages in native C definitions rather than growing the
+    textual facade into a second programming language.
+[x] Preserve and test punctuation short options used by legacy commands, and
+    make runtime-generated compact schemas own their command names rather than
+    relying on registration-call pointer lifetimes.
+[x] Identify custom multi-token option values from the parser's structural
+    result rather than a fixed backward-search window; cover values wider than
+    the built-in color/vector forms.
+[x] Reject overflowing option-builder row counts before allocating the
+    required terminal descriptor.
+
+Deep tab-completion API and scaling review (2026-08-13)
+-------------------------------------------------------
+
+[x] Separate syntax/semantic validation from candidate generation.  A
+    validation-only query must not enumerate candidates, and one completion
+    request must invoke its selected semantic completer at most once.  The
+    public `ged_cmd_validate` API now has that direct behavior; the redundant
+    completion-free validation alias was removed.
+[x] Remove generic per-candidate reconstruction and whole-command validation.
+    Select context-dependent providers once from parsed command state; expose
+    an explicit lightweight candidate predicate only for the rare rules whose
+    legality actually depends on the proposed value.
+[x] Make cursor handling correct in the middle of command, option, quoted,
+    escaped, UTF-8, object, and database-path tokens.  Track the full token,
+    decoded prefix through the cursor, raw prefix/suffix spans, and the exact
+    replacement range separately.
+[x] Add deterministic provider-call-count and mid-line replacement tests, plus
+    scaling tests which prevent broad object/path completion from regressing
+    to quadratic behavior.
+[x] Filter database directory entries by type and prefix before sorting,
+    encode each matching name once, and avoid a second whole-database search
+    for ordinary unescaped hierarchy paths.
+[x] Add a database completion index with reliable mutation invalidation so
+    root-object prefixes are O(log N + matches), while retaining command-
+    selected hidden, _GLOBAL, binary, primitive, combination, and region
+    policies.
+[x] Add a request-oriented completion API with a candidate budget, total and
+    returned counts, truncation state, and independently computed common
+    prefix.  Keep a compatibility wrapper for existing callers.
+[x] Bound transient-layout work independently of terminal dimensions.  Limit
+    materialized candidates and summary-frontier size, precompute UTF-8 widths
+    within each layout, retain the candidate set for resize-only repaints, and
+    debounce Qt resize rendering.  A 10,000-candidate/100-row regression test
+    guards the layout path.
+[x] Reuse the cursor parse throughout one completion request, avoid growing-
+    prefix revalidation in native schema analysis, and replace recursive
+    "copy schema and clear custom_validate" patterns with the explicit
+    bu_cmd_schema_validate_syntax API.
+[x] Improve experimental API ownership and clarity: const provider data,
+    status separate from count, explicit byte-offset terminology, documented
+    token-grammar candidate ownership, and removal of result fields duplicated
+    by `expected` or `hint`.
+[x] Convert the last potentially large composite database provider
+    (geometry-or-primitive) and filesystem provider to bounded query
+    interfaces, including full-set total/common-prefix metadata.  File
+    completion now scans a directory once and retains O(K) rather than O(N)
+    candidate storage for a K-entry request.
+[x] Keep parser-owned grammar adapters on the same classify-then-enumerate
+    path as flat schemas.  Native tree/form adapters and delegated commands
+    now use syntax-only validation, search publishes its context-selected
+    object provider instead of scanning directly, and custom BREP component
+    indices honor the caller's materialization budget while reporting
+    full-set count, truncation, and common-prefix metadata.
+[x] Keep the compatibility fallback for metadata-free commands on that same
+    path: syntax-only validation classifies the object/path role without a
+    database scan, and the outer request performs one bounded query.
+[x] Keep custom final-value predicates from breaking filesystem navigation or
+    bounded extension filtering.  Directory candidates remain available as
+    intermediate paths, while graph's SVG role selects an extension-aware
+    provider before applying its final-value validator.
+[x] Release the allocated NULL-only argv returned by empty command and
+    database queries; repeated no-match completion must not leak.
+[x] Re-run the full targeted completion/schema/frontend suite, repository
+    regression, and measured large-database/layout benchmarks before declaring
+    this section complete.
+
+Post-squash review and follow-up (2026-08-13)
+---------------------------------------------
+
+[x] Preserve bu_opt callback parsing without speculative NULL-storage calls.
+    Standard flags are classified from descriptor metadata, opaque callbacks
+    are invoked exactly once with their actual storage, and partially known
+    compact flag words remain untouched pass-through operands.
+[x] Apply command candidate predicates inside bounded semantic providers before
+    the materialization limit.  Report total, truncation, and common prefix for
+    the full valid set rather than for a filtered prefix of that set.
+[x] Keep hierarchical completion proportional to the selected subtree.  Slash
+    paths query only direct children of the decoded parent, and pathsum, paths,
+    and listeval now combine their space-separated path components before
+    selecting that parent.
+[x] Reduce completion-index memory by storing stable directory-entry iterators
+    in the reverse map instead of a second copy of every database object name.
+[x] Generate standard command help from schema data.  libbu now emits a
+    POSIX-style synopsis plus description, options (including aliases),
+    operands, repeated groups, and constraint hints; libged exposes the same
+    output by registered command name.  rm, list/l, and the straightforward BoT
+    command family now use generated help rather than duplicated option text.
+[x] Remove rm's growing-prefix custom-validator cost.  Its force-sensitive
+    hidden/global completion policy is selected once by a request-aware
+    semantic provider, keeping analysis of arbitrarily long rm commands linear.
+[x] Replace the gsh, MGED, and QgConsole fixed candidate limits with a shared
+    viewport-derived budget.  Truncated MGED and QgConsole displays requery
+    after resize so a larger console can expose more candidates; all frontends
+    retain the one-third-prior-output/two-thirds-completion policy.
+[x] Rename private "legacy" parser symbols that actually implement the
+    supported bu_opt descriptor callback contract.  Genuine compatibility
+    aliases remain documented as such, but bu_opt is no longer described as a
+    retirement shim.
+[x] Compile and run qgconsole_completion_modes in the shared Qt-enabled build
+    after the viewport-budget API change.  The test now declares its ProFont
+    data dependency and tells Qt's offscreen backend where build-tree fonts
+    are staged.
+[x] Restore qged's intended Inconsolata console font.  The font survived the
+    earlier console/resource refactors in the source tree, but its resource
+    entry and selection logic did not; qged once again embeds and selects it.
+Standard help and documentation audit (2026-08-13)
+--------------------------------------------------
+
+[x] Add standard synopsis/help builders for bu_opt descriptors, native flat
+    schemas, native trees, and registered GED commands.  Generated schema help
+    now includes aliases, operands, repeated groups, constraints, keyword
+    values (with aliases and descriptions), and numeric domains.
+[x] Make a shaped multi-token operand appear once in a synopsis.  For example,
+    a packed point or three XYZ words is one semantic `point`, not three
+    independently optional point values.
+[x] Audit production bu_opt users which printed a literal Usage string.  Every
+    such command/program now obtains its option list from bu_opt_help or
+    bu_opt_usage; the only metadata-free match left by the source audit is an
+    internal libbv test program.
+[x] Convert schema-backed help sites to the standard generators wherever the
+    metadata describes the executable syntax.  The pass touched 197 libged
+    implementation modules (229 help-producing source sites) and 22 executable
+    entry points, in addition to shared frontend support modules.
+[x] Correct option-definition styling in 35 AsciiDoc man pages.  Short and long
+    spellings are separate bold spans, argument metavariables are italic rather
+    than part of the option name, and definition-list punctuation is uniform.
+    All changed pages convert successfully with asciiquack's manpage backend.
+[x] Correct the metaball point metadata uncovered by the help audit.  Its
+    execution parser once again accepts both the packed and three-coordinate
+    forms, including the relative move option, and completion does not
+    revalidate an individual coordinate as a complete vector.
+
+[x] Add a first-class alternative-form abstraction to libbu.  A form should
+    have a label/description and a complete schema or tree; one form set must
+    drive validation, parsing, help, JSON, lint, and completion.  The private
+    libged native-form adapter used by who and zap is a useful prototype, but
+    keeping this concept outside the common metadata leaves commands such as
+    make_name unable to publish `template` versus `-s [number]` as exclusive
+    standard synopses.  Public form sets now drive selection, validation,
+    parsing/dispatch, help, JSON, lint, and GED completion adapters; ambiguous
+    partial forms remain incomplete and merge compatible candidates rather
+    than becoming prematurely invalid.
+[x] Add a declarative grouped-value/form facility for non-vector alternatives,
+    notably orient's packed quaternion versus four scalar components.  The
+    vector3 shape now documents ordinary packed-or-XYZ points correctly, but a
+    command-specific count validator remains opaque to help and JSON.  Named
+    argument variants now publish each accepted spelling and token width, and
+    the standard color, RGB, vector, counted-vector, optional-scalar, orient,
+    edit, faceplate, and other custom shapes use them.
+[x] Complete metadata for parser-owned and dynamically assembled command
+    families.  Search needs human descriptions on its shared term vocabulary;
+    edit, joint, faceplate, and vdraw need inspectable command/form records;
+    env needs its list/get/set forms represented rather than a raw root tail.
+    Search terms now carry shared descriptions; edit publishes its generic
+    operation tree; joint, faceplate, and vdraw expose their command records;
+    and env publishes distinct list/get/set forms.
+[x] Replace the remaining exact syntax prose in 20 production schema-bearing
+    libged modules.  Most are incomplete nested leaves or mode-dependent
+    grammars (db, comb, arb/edbot, view objects/polygons, nmg, pnts, qray,
+    facetize, and related helpers), not simple missed calls to the generator.
+    Do not delete these strings until their schemas can generate equivalent
+    output; doing so would make help less correct while concealing missing
+    specifications.  The nested db, comb, arb/BoT, view object/polygon/
+    faceplate, NMG, pnts, qray, analyze, and facetize paths now generate their
+    structural help from schemas or form/tree metadata.
+
+[x] Correct executor/metadata mismatches found while replacing the remaining
+    faceplate help.  Rectangle backgrounds are colors, the executable axes
+    spelling is `axes_color`, Boolean values are limited to zero or one,
+    positive/nonnegative numeric domains are shared by validation and help,
+    parameter setters read the supplied value rather than the subcommand name,
+    and invalid colors/font sizes no longer use uninitialized storage.
+[x] Add concise one-sided integer and number range initializers and option/
+    operand macros so common positive, nonnegative, ceiling, and floor domains
+    do not need artificial maximum values or custom validators.
+[x] Treat generated help metadata as the executable contract rather than
+    reproducing known defects in historical prose.  Correct stale MGED help
+    exit-status expectations and make invalid hierarchical completion parents
+    return zero candidates instead of a positive error code that could be
+    mistaken for a materialized result.
+
+Lower-priority follow-up opportunities
+---------------------------------------
+
+These are not recommended as merge blockers.  They are deliberately deferred
+because the current measured paths are bounded and the additional abstraction
+would be a substantially larger API change without a demonstrated caller need.
+
+* Continue opportunistically migrating schema-backed commands that still
+  assemble usage/options prose by hand.  The generator is now the normative
+  path; command-specific examples, caveats, and extended explanations should
+  be appended after its output rather than restating syntax.  This is ongoing
+  maintenance rather than a finite merge-readiness defect.
+* A public parsed-command/scan object could share work across separate calls to
+  analysis, validation, option-presence, and completion.  Within an individual
+  completion request the parse is already shared; most callers make only one of
+  these queries, so a public lifetime-bearing object would currently add more
+  ownership complexity than saved work.
+* Structured candidate records could carry distinct insertion and display
+  strings.  Providers currently return values in their declared token grammar
+  and frontends own shell/Tcl display encoding.  Introduce records only if a
+  provider needs genuinely different insertion and display values; doing it
+  speculatively would make every simple provider more verbose.
+* Parser-owned languages such as search may eventually expose one inspect tree
+  for execution, validation, completion, and JSON.  They are intentionally
+  retained as parser-owned grammars today: forcing them into the ordinary
+  option schema would duplicate their language or turn the compact schema DSL
+  into a general parser generator.
+
+Deep post-rebase review follow-up (2026-08-14)
+----------------------------------------------
+
+[x] Make every BU_CMD_VALUE_CUSTOM parser honor NULL storage as a
+    side-effect-free validation request.  Correct the pnts radius, radii, and
+    thread-count consumers and test all three through schema validation.
+[x] Fully initialize transient bu_cmd_schema records built by the bu_opt
+    adapters, including cases and terminal-action metadata.  Exercise them
+    with poisoned stack storage in parsing and validation tests.
+[x] Release ged_cmd_analysis storage on every completion path, including the
+    public context result, and add a repeated completion ownership regression.
+[x] Make QgConsole completion rows genuinely transient: displaying, resizing,
+    and removing candidates must never evict or alter permanent console
+    history, even when the document is at its maximum block count.
+[x] Pass QgConsole's complete editable command and cursor byte offset to GED
+    completion so mid-token and mid-line replacement preserves the suffix.
+    Apply the same rule to preview filtering.
+[x] Recompute MGED wrapped-input erase geometry using the current terminal
+    width after resize.  Cover both narrowing and widening long input.
+[x] Separate executable form selection from interactive continuation so a
+    valid short form does not hide candidates from a viable longer form.
+[x] Make command-tree/form dispatch honor the root schema and all child-phase
+    policies, including root options, fixed operands, aliases, and nesting.
+[x] Replace the O(candidate_count * row_count) full-layout search with a
+    bounded or incremental algorithm and test the narrow/tall maximum-budget
+    case.
+[x] Replace compact bu_opt's repeated prefix validations with one structural
+    analysis and one custom validation per actual option value.
+[x] Bound the database completion cache by retained bytes/candidates, use a
+    useful eviction policy, and avoid retaining very large materialized query
+    vectors.
+[x] Apply filesystem candidate predicates during the directory scan rather
+    than materializing an unbounded pre-filter result.
+[x] On gsh resize, rebuild both the displayed and selectable completion state
+    while preserving the selected value when possible.
+[x] Avoid repeated DSR timeout delays and preserve non-DSR input bytes when a
+    terminal does not answer cursor-position queries.
+[x] Add one authoritative completion-result merger which preserves limits,
+    full-set totals, truncation, common prefixes, and deduplication when static
+    and semantic candidates are combined.
+[x] Unify libbu and GED schema linting and run it transactionally on the exact
+    schema being registered.  Diagnose unknown semantic providers without
+    emitting pre-main log output.
+[x] Make rich keyword linting reject every canonical/alias collision,
+    including a later canonical matching an earlier alias and duplicate
+    aliases within one row.
+[x] Use the shared Boolean reader for syntax validation so validation and
+    execution agree for empty and malformed attached values.
+[x] Define a portable C++ binding policy for schema storage.  Keep byte-offset
+    bindings limited to standard-layout records and provide an explicit
+    alternative for non-standard-layout command state.
+[x] Reuse QgConsole's completion model rather than accumulating parented
+    QStringListModel objects over repeated updates.
+[x] Extend the focused and stress suites to cover every defect above, then run
+    the all-target Ninja build, completion/schema/frontend suites, repository
+    regression, and git diff checks.
+
+Post-squash deep review follow-up (2026-08-14)
+-----------------------------------------------
+
+[x] Preserve an explicit decoded-byte-to-raw-byte boundary map while MGED
+    normalizes Tcl words for completion.  Use that map for replacement and
+    cursor offsets so quoting and backslash substitution cannot corrupt the
+    original command.  Cover quoted words, escaped spaces, escaped slashes and
+    backslashes, UTF-8, and mid-token suffixes; the current m35.g reproducer
+    turns `draw component\/suspension/r2` into
+    `draw component\/suspensionr22`.
+[x] Make dynamic command and schema loading one retained, transactional
+    operation.  Never register schema pointers from the temporary inspection
+    handle when the generalized plugin load failed, and do not publish an
+    executable command if its metadata is malformed.  Add a plugin fixture
+    with a rejected generic manifest and an otherwise readable schema
+    manifest to guard against dangling registry pointers.
+[x] Publish each command implementation, compatibility alias, and exactly one
+    metadata kind atomically.  Treat duplicate metadata as part of the same
+    first-wins decision, roll back on failure, serialize initialization
+    diagnostics, and stress simultaneous duplicate registration to prove that
+    an implementation cannot be paired with another declaration's schema.
+[x] Make built-in semantic-provider ownership independent of call order.
+    Install built-ins before accepting public registrations, reserve the
+    `ged.*` namespace (or require an explicit override policy), and test an
+    attempted built-in-name registration before the first lookup.
+[x] Give semantic providers a complete C-facing contract.  Publish their
+    result value type and capability flags in the provider record rather than
+    classifying built-ins with string comparisons, document candidate/result
+    ownership, and keep the implementation free to own registration records
+    with C++17 RAII.  Ensure shutdown removes custom provider data before its
+    documented lifetime ends.
+[x] Define and test libged lifecycle semantics.  Either make shutdown a
+    synchronized terminal state which rejects every later registry operation,
+    or make initialization and teardown repeatable; do not leave command,
+    schema, or semantic-provider registries in different generations.  Clear
+    metadata before unloading the modules which own its callback and string
+    pointers.
+[x] Compute every full-set common prefix on a valid UTF-8 boundary in the
+    shared completion layer rather than repairing it in individual
+    frontends.  Make QgConsole's command, candidate, and source-offset
+    conversions explicitly UTF-8 instead of locale-dependent local-8-bit
+    conversions, and cover candidates whose first differing code points share
+    an initial UTF-8 byte.
+[x] At an empty search path/expression position, merge bounded database-path
+    candidates with the valid static search options and expression terms.
+    Preserve hidden-object policy and exact total/truncation/common-prefix
+    metadata while ensuring `_GLOBAL` remains excluded from ordinary search
+    path completion.
+[x] Validate and normalize semantic-provider output at the registry boundary:
+    candidate pointer/count consistency, total count no smaller than the
+    materialized count, truncation consistency, bounded materialization, and a
+    valid full-set common prefix.  Clamp frontend summary arithmetic as a
+    defensive fallback and add malformed-provider tests.
+[x] Reduce compact GED declaration boilerplate without inferring semantic
+    aliases from storage or help text.  One typed GED_RULE_* table now holds
+    aliases, forms, database roles/type cases, semantic refinements,
+    constraints, and validators and is normalized into owned schema storage
+    once at registration.  All 17 production sources which formerly needed
+    compact metadata sidecars use the table, identical metadata can name
+    multiple options in one row, and all 40 BU_OPT_DESC_BUILDER definitions
+    use the concise BU_OPT_* field-binding rows wherever the callback binds an
+    ordinary argument field.  The remaining raw rows intentionally pass the
+    whole argument record to custom readers.  Explicit compatibility aliases
+    are covered by registry JSON tests rather than guessed from shared
+    storage; the source audit prevents a return to per-kind sidecars or raw
+    conditional field bindings.
+[x] Consolidate the duplicated bu_opt-to-native-schema adapter logic in libbu
+    and libged so type, arity, optional-value, shaped-value, alias, validator,
+    and standard-candidate inference have one implementation.  Likewise share
+    and cache search's immutable type vocabulary instead of rebuilding and
+    maintaining it in both the generic provider and parser-owned grammar.
+[x] Resolve aliases during the shared adapter build.  An alias inherits the
+    canonical option's type, shape, cardinality, candidates, validator,
+    semantic role, and argument requirement unless it explicitly overrides
+    presentation metadata.  Reject unknown targets and cycles, remove the
+    typed-alias workaround, and verify parse/help/JSON/completion equivalence
+    for standard and opaque option readers.
+[x] Make flat-rule declarations counted.  Add a rule count to ged_opt_spec,
+    derive it in declaration macros, and stop reading caller memory in search
+    of a missing sentinel.  Preserve GED_RULE_NULL as an optional readability
+    marker only if doing so cannot conceal an incorrect count.
+[x] Make the first broad root completion scale as well as repeated queries.
+    Add a genuinely cold 100k-object test, then replace the per-entry map build
+    and full matching-range scan for built-in policies with a prefix-oriented
+    index carrying aggregate count/common-prefix metadata and bounded ordered
+    materialization.  Retain a scan fallback for arbitrary candidate filters
+    and verify database mutation invalidation.
+[x] Debounce QgConsole semantic highlighting so ordinary edits do not
+    synchronously reparse the entire command on every keystroke.  Split the
+    largest new implementation and test files by responsibility after the API
+    behavior is settled, preserving the existing focused and scaling
+    coverage.
+[x] Modularize the corrected implementation along useful ownership boundaries.
+    Database completion generations and command-input parsing now have focused
+    C++17 modules; the immutable search vocabulary belongs to librt; registry
+    lifecycle/plugin transactions and scaling have independent tests; MGED and
+    QgConsole retain their frontend-offset suites.  Keep the public libbu and
+    libged boundaries C-only and document the new public adapter functions.
+
+Steady-state review follow-up (2026-08-14)
+------------------------------------------
+
+[x] Extend the libged activity lease beyond command execution.  Help, JSON,
+    lint, validation, analysis, completion, form/tree adapters, and semantic
+    provider callbacks must remain valid while shutdown waits; registrations
+    attempted during teardown must be rejected deterministically.
+[x] Enforce one metadata representation across every registration entry point,
+    reject malformed or reserved command names before normalization can split
+    implementation and metadata keys, and cover direct-API collisions.
+[x] Preserve natural candidate ordering for bounded broad-prefix index queries.
+    Replace the lexical fast-path with a range-minimum natural-rank index so a
+    100,000-match query remains O(log N + K log N) without changing behavior.
+[x] Reject truncated semantic-provider results that cannot prove a valid UTF-8
+    common prefix for the complete filtered set, and add a malformed bounded
+    provider regression.
+[x] Give ged_cmd_lookup a stable documented result lifetime and omit synthetic
+    `_mged_` aliases; its current pointer refers to a destroyed foreach
+    snapshot as soon as the function returns.
+[x] Propagate parser, grammar, and semantic-provider failures through the
+    bounded completion API; reject inconsistent truncated materializations,
+    distinguish a valid empty common prefix from missing metadata, and remove
+    the arbitrary 65,536-entry ceiling from explicitly unbounded queries.
+[x] Make outward-facing validation, analysis, and completion metadata strings
+    result-owned before releasing the registry lease.  Fix the command-name
+    completion snapshot leak, retain repeated analysis strings in one
+    deduplicated allocation instead of two allocations per token, and verify
+    retained results remain valid across shutdown and repeated clear
+    operations.
+[x] Remove quadratic compact-schema highlighting.  Resolve option-selected DB
+    providers once per complete argv with a private analysis plan, apply later
+    context options consistently to earlier operands, and cover a 5,000-value
+    `ls ... -a` analysis workload.
+[x] Finish the completion-index and metadata ownership cleanup.  Build policy,
+    natural-order, and range-minimum views only when requested; share the DB
+    path encoder and object-policy predicate rather than maintaining parallel
+    copies; make command-list snapshots explicitly owned/NULL-terminated; and
+    require every parser-owned grammar to provide generated help.  Give the
+    analysis result the same explicit initializer/reusable-result contract as
+    validation and completion results.
+[x] Release the temporary argv used by filtered bu_opt help generation; the
+    richer standard-help path makes repeated filtered descriptions a normal
+    API use rather than a one-shot process-lifetime allocation.
+[x] Release gsh's owned command-list snapshot after `--command-schema all`;
+    the newly explicit ged_cmd_list ownership contract applies to early-exit
+    introspection paths as well as interactive completion.  Update the schema
+    round-trip and plugin-enumeration tests to follow the same contract.
+[x] Make natural completion ordering a total order.  Numerically equivalent
+    spellings such as `1` and `01` must have a deterministic lexical tiebreak
+    so bounded index queries, heaps, and full-result normalization agree; use
+    relational comparison rather than overflowing unsigned subtraction for
+    maximum-width numeric suffixes.
+[x] Enforce exact truncated-result metadata at the final completion boundary,
+    not only for named semantic providers.  Parser-owned grammar callbacks
+    must supply a full-set total and allocated (possibly empty) common prefix;
+    never derive insertion text from an arbitrary displayed subset.  Apply
+    the same UTF-8, prefix, uniqueness, filter, budget, and natural-order
+    normalization to grammar materializations as to named providers.
+[x] Make every reusable public validation, analysis, and completion result
+    transactional on failure.  Clear old contents before argument/lifecycle
+    checks and clear partially populated grammar/tree/form callback output on
+    error, so frontends never retain stale metadata or need callback-specific
+    failure cleanup.  Exercise deliberately failing grammar callbacks and an
+    invalid bounded-completion request with previously populated results.
+[x] Clamp cursor offsets once at the shared command-input parser boundary so
+    validation adapters cannot publish source spans beyond the supplied input
+    when an editor reports a stale or oversized cursor position.
+[x] Make natural ordering independent of machine integer width and C numeric
+    syntax.  Compare arbitrary-length decimal digit runs directly, retain a
+    deterministic lexical tiebreak for equivalent zero-padded spellings, and
+    cover values beyond ULONG_MAX in bounded and unbounded indexed queries.
+[x] Enforce the counted flat-rule contract.  A retained GED_RULE_NULL visual
+    terminator is valid only as the final counted row; reject a premature END
+    rather than silently hiding subsequent author declarations.
+[x] Apply the reusable-result transaction contract uniformly at the libbu
+    boundary.  Descriptor, builder, schema, shaped-value, tree, and form
+    validation now release stale and partially callback-populated candidates
+    on every failure.  An empty command-schema result reports an unknown role
+    rather than misleadingly defaulting to string; focused tests reuse seeded
+    results across invalid arguments, builder failures, and failing callbacks.
+[x] Bound the database index's policy-view cache, not only its returned
+    candidate vectors.  Ignore unsupported flag bits when selecting a view
+    and evict least-recently-used O(database-size) policy arrays after a fixed
+    limit; exercise normalization and eviction against the 100,000-object
+    database.
+[x] Document borrowed registration lifetimes consistently for command,
+    native-schema, compact-schema, grammar, and semantic-provider metadata,
+    including the transactional failure rule for parser-owned callbacks.
+[x] Re-run the all-target build, focused 100,000-object and lifecycle races,
+    exhaustive completion corpus, frontend tests, repository/license checks,
+    and final diff audit after these fixes.
+
+Verification notes
+------------------
+
+* The final steady-state pass completes warnings-as-errors all-target rebuilds
+  after the result-ownership and bounded policy-cache fixes (1,168 actions for
+  the consistent rebuild and 154 actions after the last source audit).  All
+  126 selected libbu, schema, lifecycle, 100,000-object, exhaustive corpus,
+  Qt, gsh, MGED GUI/PTY, native-source, repository, license, and change-policy
+  tests pass in 14.19 seconds.  The cold scale test, including 64 policy-cache
+  probes, finishes in 6.90 seconds.  Focused Memcheck runs report no definite
+  leaks or invalid accesses for command schemas, failing bu_opt callbacks, or
+  registry/plugin shutdown.  git diff --check is clean.
+
+* The final post-squash implementation completes a 1,607-action all-target
+  Ninja rebuild.  The 125-test focused selection passes in full after the new
+  lifecycle test was brought into repository-policy compliance: all bu_opt
+  and command-schema tests, both command-analysis datasets, the exhaustive
+  completion corpus, the cold 100,000-object scale test, registry/plugin
+  lifecycle transactions, Qt console behavior, gsh and MGED terminal/GUI
+  paths, native-schema source audit, license and change-policy checks, and
+  regress-repository.  The scale test takes 5.12 seconds including database
+  construction, and the completion corpus takes 11.88 seconds.
+
+* The post-squash follow-up adds a cold 100,000-object root benchmark, a
+  rejected-manifest plugin fixture, concurrent command/schema publication,
+  repeatable shutdown/provider cleanup, counted-rule, alias-chain, malformed
+  provider, UTF-8, Tcl quoting/backslash, Qt debounce, and search-union
+  regressions.  The focused completion-scale test finishes in under four
+  seconds in the unoptimized warnings-as-errors build; warm broad-prefix
+  materialization is required to remain below 250 ms.
+
+* The compact-rule and option-row cleanup completes an all-target Ninja build
+  and passes all 135 focused libbu option/schema/help, GED command/completion,
+  Qt console, gsh, MGED, source-audit, repository, license, and change-policy
+  tests.  Runtime schema checks cover every compact command alias declaration,
+  and git diff --check is clean.
+* The 2026-08-14 post-rebase follow-up completes an all-target Ninja build and
+  passes all 118 focused bu_opt, schema, file, line-editor, command-analysis,
+  completion-corpus, Qt console, gsh, MGED, and source-audit tests.  The
+  repository and license regressions pass, and git diff --check is clean.
+* The post-review all-target Ninja rebuild completes successfully.  The final
+  focused pass covers all 100 libbu schema/bu_opt/line-editor tests, both
+  libged command-analysis suites, seven gsh/MGED terminal completion tests,
+  the MGED completion bridge, and the repository and license regressions.
+  git diff --check is clean.
+* The final help/form follow-up completes a 1,762-action all-target Ninja
+  rebuild and passes 118 focused schema, bu_opt, completion-corpus, Qt console,
+  gsh, MGED, and license tests, plus regress-repository.
+* The Ninja build completes successfully.
+* The schema, command-analysis, completion-corpus, gsh PTY, MGED PTY/bridge,
+  bu_opt compatibility, BoT, license, and repository regression tests pass.
+* The gsh resize/cursor PTY test passes repeatedly to exercise its timing path.
+* The shared Qt-enabled Debug build compiles qged and libqtcad with warnings as
+  errors and passes qgconsole_completion_modes using its declared build-tree
+  font dependency.
+* A post-rebase full 1,277-test CTest run completed with 1,274 passes.  One
+  failure is the intentional test-target sentinel.  The native-schema source
+  audit exposed an over-broad policy check and now passes after limiting the
+  bu_opt exemption to a non-command scalar-reader source.  slow-bigdb_5gb was
+  killed under the eight-way full-suite memory load and passed alone in 70.6
+  seconds.  All other tests, including bu_process_all, both fbserv stress
+  tests, changes-rules, GQA, and all drawing tests, passed in the full run.
+* The fbserv quick and heavy stress suites pass ten consecutive runs with both
+  suites launched concurrently after assigning automatic invocations disjoint
+  bounded port slots.
+* The MGED GUI binding test and all MGED CLI/completion tests pass after the
+  Configure binding correction; repository and license regressions also pass.
+* All 97 bu_opt tests and both command-analysis suites, including the m35.g
+  completion corpus, pass with the compact positional DSL enabled.
+* On m35.g in the Debug build, `ls ` completion generation drops from about
+  5.15 seconds to 11 milliseconds.  A 100-column, 30-row summary drops from
+  about 486 to 315 milliseconds; the normal two-row GUI budget takes about 14
+  milliseconds.  Empty `ls ` completion contains objects only, while `ls --`
+  offers all ten long options.
+* The deep-review final tree completes the all-target Ninja build, passes
+  git diff --check and regress-repository, and passes all 118 targeted libbu,
+  schema, command-analysis, completion-corpus, gsh, and MGED tests.  The
+  100,000-object analysis/scaling test, including the broad empty-prefix
+  `ls /` case, `draw /`, composite geometry-or-primitive queries, and cache
+  mutation checks, finishes in about 2.9 seconds.  The 10,000-candidate/100-row
+  layout test finishes as part of a 0.27-second line-editor test.
+* A focused Memcheck replay of the delegated `blast` grammar passes after
+  correcting its transferred common-prefix ownership.  The exhaustive native
+  completion corpus passes in 11.4 seconds; its optional whole-corpus Memcheck
+  run was stopped after more than twelve CPU-bound minutes with stable memory
+  and no diagnostics.
@@ -47,7 +47,7 @@ Set the output width in pixels.
 *-n* _height_::
 Set the output height in pixels.

-*-h, -?*::
+*-h*, *-?*::
 Print a usage message and exit.

 [[examples]]
@@ -76,7 +76,7 @@ Outputs to the specified framebuffer instead of the one specified
 by the `FB_FILE` environment variable. If this is the last option,
 the *-F* prefix is optional.

-*-h, -?*::
+*-h*, *-?*::
 Print a usage message and exit.


@@ -56,6 +56,27 @@ display window of its own.
  update logic instead of the traditional command set. Primarily of use for
  development and testing of the next-generation command behavior.

+*--completion-mode=mode*::
+  Select the interactive completion policy.  Supported values are *filter*,
+  *cycle*, *prefix*, *legacy*, and *off*.  See *brlcad-completion*(5).
+
+*--command-schema=command|all*::
+  Print the registered static command grammar as JSON and exit.  A command
+  name prints one grammar; *all* prints a JSON array for the full discoverable
+  LIBGED registry.  Runtime-dependent semantic providers are identified by
+  name, allowing external syntax highlighters and ANTLR grammar adapters to
+  consume the static command structure without opening a database.
+
+[[environment]]
+== ENVIRONMENT
+
+*BRLCAD_GSH_COMPLETION_MODE*::
+  Sets GSH's completion mode when *--completion-mode* is not specified.
+
+*BRLCAD_COMPLETION_MODE*::
+  Sets the shared BRL-CAD completion mode when no GSH-specific setting is
+  present.  See *brlcad-completion*(5) for mode behavior and precedence.
+
 [[examples]]
 == EXAMPLES

@@ -81,6 +102,18 @@ not a terminal, *gsh* executes each line in turn with no prompt, reporting the
 database title, an object listing, and a summary of the contents of `moss.g`.
 ====

+.Publish command grammars for an external tool
+====
+[source,bash]
+----
+gsh --command-schema draw > draw-schema.json
+gsh --command-schema all > ged-schemas.json
+----
+The first form emits one flat command schema.  The second emits every flat,
+nested, context-selected, and parser-owned static grammar registered by
+LIBGED.
+====
+
 .Inspect and modify geometry interactively
 ====
 [source,bash]
@@ -100,7 +133,7 @@ LIBGED commands available here are shared with *mged*(1) and *archer*(1).
 [[see_also]]
 == SEE ALSO

-*brlcad*(1), *mged*(1), *archer*(1), *btclsh*(1)
+*brlcad*(1), *mged*(1), *archer*(1), *btclsh*(1), *brlcad-completion*(5)

 [[author]]
 == AUTHOR
@@ -217,6 +217,11 @@ _MGED_ searches for a startup configuration file (`.mgedrc`) in three locations,
 . If the environment variable `HOME` is set, `$HOME/.mgedrc` is used.
 . If `.mgedrc` exists in the current working directory, it is used.

+The command prompt completion policy may be persisted with
+`set mged_default(completion_mode) mode` in _.mgedrc_, or selected with the
+*BRLCAD_MGED_COMPLETION_MODE* and *BRLCAD_COMPLETION_MODE* environment
+variables.  See *brlcad-completion*(5) for the supported modes and precedence.
+
 The first file found is used and the others are ignored. Use *--rcfile* to specify an explicit path, or *--no-rc* to skip rc file processing entirely.

 Command-line options that affect MGED variables (all the long options listed above) are applied _after_ the rc file is processed, so they always take precedence.
@@ -350,7 +355,7 @@ user:~**mged --rset "g snap 1" --rset "g rh 10" model.g**

 _Computer Graphics for Target Descriptions_, BRL Technical Report ARBRL-TR-02480, _GED: An Interactive Solid Modeling System for Vulnerability Assessments_

-*brlcad*(1), *rt*(1), *comgeom-g*(1), *vdeck*(1), *librt*(3)
+*brlcad*(1), *rt*(1), *comgeom-g*(1), *vdeck*(1), *librt*(3), *brlcad-completion*(5)


 [[diagnostics]]
@@ -96,6 +96,11 @@ When standard input is not a terminal (for example, when it is redirected from a
 *-B*::
  Deprecated and no longer used; accepted but ignored.

+For each color option, the three channels may be supplied as one packed
+_r/g/b_, _r,g,b_, or _r;g;b_ argument, or as three separate _r g b_
+arguments.  The packed compatibility color forms historically accepted by
+*nirt* continue to work as well.
+
 *nirt* also checks for a `.nirtrc` start-up file, first in the current directory and then in the user's home directory. If found, it is read before interaction begins and may contain any *nirt* commands, which is useful for loading predefined states or output formats.


@@ -4,38 +4,54 @@
 :manmanual: BRL-CAD

 == NAME
-pixdiff - highlight samples which differ between two pix or bw files
+pixdiff - highlight differences between two pix or bw images

 == SYNOPSIS

 [source]
 ----
 pixdiff _file1.pix_ _file2.pix_ > _out.pix_
-pixdiff _file1.bw_ _file2.bw_ > _out.bw_
+pixdiff -b _file1.bw_ _file2.bw_ > _out.bw_
 ----


 [[description]]
 == DESCRIPTION

-*pixdiff* compares two raw *pix*(5) or *bw*(5) images byte by byte and
-writes a difference image of the same size to standard output. Bytes that
-differ by +/-1 are written at intensity 192, while larger differences are
-written at full intensity 255. Matching bytes are written at half their
-original intensity, providing visual context for locating differences.
+By default, *pixdiff* compares raw *pix*(5) images as RGB pixels and writes
+a PIX difference image to standard output. When all three channels of a
+pixel match, it writes a dim grayscale version of that pixel to all three
+output channels. When any channel differs, each matching channel is written
+as zero, each channel differing by one is written as 192, and each channel
+differing by more than one is written as 255.

-Because the comparison does not interpret pixel structure, no format option
-is needed and *pixdiff* is independent of image resolution. The two inputs
-must be the same size in bytes; otherwise the program reports the mismatch
-and exits. Either input file may be given as
+With *-b*, *pixdiff* compares raw *bw*(5) images one byte at a time and
+writes a BW difference image. Differing samples use the same 192 and 255
+intensities; matching samples are written at half their original intensity.
+
+No image dimensions are needed. The two inputs must be the same size in
+bytes, and PIX input must contain complete three-byte pixels. Otherwise,
+*pixdiff* reports an error. Either input file may be given as
 *-* to read from standard input. Output must be redirected; *pixdiff*
 refuses to write a raw image stream to a terminal.

-Upon completion, the count of bytes that matched, that were off by 1, and
-that were off by many is reported on standard error.
+Upon completion, *pixdiff* reports matching, off-by-one, and larger-difference
+channel or sample counts on standard error.

-Also see *bwdiff*(1), which can also operate on *pix*(5) files and can
-produce other kinds of difference output.
+*bwdiff -n -b* produces a similar BW highlight image, but writes 255 rather
+than 192 for off-by-one differences. The default *bwdiff*(1) output instead
+shows signed differences around a neutral gray.
+
+
+[[options]]
+== OPTIONS
+
+*-b*::
+Treat both inputs and the output as one-byte-per-pixel BW images. Without
+this option, use three-byte-per-pixel PIX images.
+
+*-h*::
+Show usage information.


 [[examples]]
@@ -59,10 +75,10 @@ on standard error give a quick quantitative sense of how much changed.
 ====
 [source,bash]
 ----
-pixdiff depth_a.bw depth_b.bw > depth_diff.bw
+pixdiff -b depth_a.bw depth_b.bw > depth_diff.bw
 ----
-Writes a grayscale highlight image using the same byte comparison and
-statistics as the color example; no format option is needed.
+Writes a grayscale highlight image using byte-wise comparison. Matching
+samples retain half their input intensity as context.
 ====


@@ -126,7 +126,7 @@ WARNING: The terminology and output format of *rtarea* may change in future rele
 *-X* _#_::
  Set *rt* program/optical debug flags as a hexadecimal bit vector.

-*-? or -h*::
+*-?*, *-h*::
  Print a usage summary and exit.

 [[examples]]
@@ -91,7 +91,7 @@ options most relevant to overlap checking are listed below.
  Whether *librt*(3) retains air-coded regions (0 = discard air, the
  default; 1 = keep air).

-*-+ t*::
+*-+* _t_::
  Emit the plot data in ASCII text format rather than the default binary
  *plot3*(5) encoding.

@@ -107,7 +107,7 @@ also honored; see that manual page for the complete list.
 *-X* _#_::
  Set *rt* program/optical debug flags as a hexadecimal bit vector.

-*-? or -h*::
+*-?*, *-h*::
  Print a usage summary and exit.

 See *rt*(1) for the remaining shared options (e.g. *-g*/*-G* grid cell
@@ -125,7 +125,7 @@ also honored; see that manual page for the complete list.
 *-X* _#_::
  Set *rt* program/optical debug flags as a hexadecimal bit vector.

-*-? or -h*::
+*-?*, *-h*::
  Print a usage summary and exit.

 See *rt*(1) for the remaining shared options (e.g. *-T* tolerances, *-c*
@@ -18,7 +18,8 @@ Link with *-lanalyze*.
 The public interface is organized across the headers included by
 _analyze.h_, including _analyze/diff.h_, _analyze/density.h_,
 _analyze/grid.h_, _analyze/heal.h_, _analyze/info.h_, _analyze/pnts.h_,
-_analyze/polygonize.h_, _analyze/nirt.h_, _analyze/voxelize.h_, and
+_analyze/contour.h_, _analyze/polygonize.h_, _analyze/nirt.h_,
+_analyze/voxelize.h_, and
 _analyze/worker.h_.

 == DESCRIPTION
@@ -32,7 +33,7 @@ to gather the information they need.
 Facilities provided by the library include model differencing, material
 density and mass property analysis, ray-based gridding and sampling,
 geometry healing, model information queries, point-cloud generation and
-processing, polygonization and voxelization of geometry, and the
+processing, manifold dual contouring and voxelization of geometry, and the
 interactive ray-tracing engine used by the *nirt*(1) command. A parallel
 worker interface supports distributing analysis work across multiple
 threads.
@@ -68,3 +68,499 @@ This software is Copyright (c) 2004-2026 United States Government as represented
 == BUG REPORTS

 Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org
+
+== Compact command schemas
+
+The `bu_cmd_schema` API in `bu/cmdschema.h` is the full-description face of the
+command engine, adding typed operands, validation, completion metadata,
+constraints, declarative numeric ranges, and machine-readable publication.
+
+The established `bu_opt` API remains the succinct option-only face of the same
+engine.  Its descriptor table and `bu_opt_*` reader callbacks are appropriate
+when a caller only needs conventional option parsing and a leftover argument
+list.  It also supplies lightweight completion and validation without forcing
+the caller to rewrite those option rows as a second table.
+
+`bu_opt_desc_value_type` recognizes every standard reader in `bu/opt.h`:
+`bu_opt_bool`, `bu_opt_int`, `bu_opt_long`, `bu_opt_long_hex`,
+`bu_opt_incr_long`, `bu_opt_fastf_t`, `bu_opt_char`, `bu_opt_str`,
+`bu_opt_vls`, `bu_opt_color`, `bu_opt_vect_t`, `bu_opt_lang`, and
+`bu_opt_man_section`; a null reader is a flag.  `bu_opt_desc_validate` uses
+that information to complete option spellings, validate supplied values, and
+report incomplete multi-token colors and vectors without invoking a custom
+reader or modifying caller state.
+
+Opaque readers may be described by a `bu_opt_value_spec` sidecar.  A row may
+override the inferred value class, publish fixed candidates, specify a hint or
+variable token cardinality, identify a separate spelling as an alias, and
+install a side-effect-free validation callback.
+The callback receives the full argv, cursor index, caller context, and row data
+for context-dependent value rules.  Standard readers need no sidecar.
+
+For reentrant use, define one ordinary initializer-row macro and pass it to
+`BU_OPT_DESC_BUILDER`.  The generated file-local builder binds fields in a
+caller-owned argument record during parsing and leaves them unbound for help
+or validation.  `bu_opt_parse_build`, `bu_opt_describe_build`, and
+`bu_opt_validate_build` perform those projections.  The generated row count is
+derived from the local array rather than repeated by the command author.
+
+The API provides three views of the same schema:
+
+* `bu_cmd_schema_parse` binds command-line options to a caller-owned argument
+  structure.  The argument pointer may be null for an optionless schema,
+  because there is then no storage to bind.  `bu_cmd_schema_parse_complete`
+  additionally requires all positional roles to satisfy their declared
+  cardinality and scalar rules.  `bu_cmd_schema_parse_known` consumes only
+  recognized options for layered parsing.
+* `bu_cmd_schema_describe` produces command help, while
+  `bu_cmd_schema_describe_json` produces machine-readable metadata.
+* `bu_cmd_schema_validate` performs side-effect-free incremental syntax and
+  scalar-type validation, returning static candidates for completion and
+  highlighting.  `bu_cmd_schema_validate_ctx` adds an optional host context
+  for semantic rules that need live application state, while preserving the
+  same native option and operand grammar.
+
+The validation result owns its candidate array.  Initialize it with
+`BU_CMD_VALIDATE_RESULT_NULL` and release it with
+`bu_cmd_validate_result_clear` after each use.
+
+For presentation, `bu_cmd_completion_layout_create` arranges a candidate set
+for a known terminal width.  It emits the complete sorted set, or a complete
+optimized prefix-bin frontier, in no more than the requested number of rows
+when that fits.  Otherwise it emits one partial summary row ending in an
+explicit omitted-candidate count, without changing the original candidate
+array used for insertion and cycling.  Initialize its result with
+`BU_CMD_COMPLETION_LAYOUT_INIT_ZERO` and release it with
+`bu_cmd_completion_layout_clear`.
+
+=== Declaring a simple schema
+
+Define an argument structure with the command defaults, then declare options
+using the `BU_CMD_*` helpers.  Each option names its short spelling, long
+spelling, storage field, value type, argument label, and help text once.
+
+Use `BU_CMD_COUNTING_FLAG` for a repeatable no-argument option whose integer
+storage field must count occurrences (for example, `-vv`).  Ordinary
+`BU_CMD_FLAG` options remain boolean even when they are repeated.
+`BU_CMD_CUSTOM_FLAG` is the deliberate escape hatch for an order-sensitive
+no-argument state transition; its parser receives a NULL argument and the
+selected storage-field address.
+
+Use `BU_CMD_OPTIONAL_STRING` for a conventional `--option [text]` form.  It
+binds the next non-option word when present, but leaves a following option for
+the regular option scanner; pass a literal text value beginning with `-` using
+the attached `--option=value` spelling.
+
+`BU_CMD_DB_OBJECT` and `BU_CMD_DB_PATH` are compact typed-option forms for
+database object and path values.  They keep libbu application-neutral: an
+application such as GED may infer its default semantic provider from the value
+type, while a specialized role may name an explicit provider in its full
+`bu_cmd_option` or `bu_cmd_operand` row.
+
+[source,c]
+----
+struct example_args {
+    int verbose;
+    fastf_t scale;
+    const char *output;
+};
+
+static const struct bu_cmd_option example_options[] = {
+    BU_CMD_FLAG("v", "verbose", struct example_args, verbose,
+                "Enable diagnostic output"),
+    BU_CMD_NUMBER("s", "scale", struct example_args, scale, "factor",
+                  "Scale the result"),
+    BU_CMD_FILE("o", "output", struct example_args, output, "file",
+                "Write the result to a file"),
+    BU_CMD_OPTION_NULL
+};
+----
+
+Aliases use `BU_CMD_ALIAS_SHORT` or `BU_CMD_ALIAS_LONG` and name the canonical
+option.  Hidden aliases remain accepted by the parser but are omitted from
+help and completion.  Custom values use `BU_CMD_CUSTOM`; their parser receives
+a pointer to that option's storage during execution and a null storage pointer
+during validation, so custom parsers must treat a null pointer as a
+side-effect-free syntax check.
+
+Typed options and operands may also use a `BU_CMD_*_VALIDATE` helper
+(`BU_CMD_OPERAND_VALIDATE` for a positional role).  Its validator is called
+without storage during incremental validation; option parsing applies it when
+binding execution storage, and a command's positional parser can reuse the
+same function.  This publishes constraints such as an integer range without
+reducing the value to an opaque custom value.
+
+For common scalar ranges, use `BU_CMD_POSITIVE_INTEGER`,
+`BU_CMD_NONNEGATIVE_INTEGER`, `BU_CMD_POSITIVE_NUMBER`, or
+`BU_CMD_NONNEGATIVE_NUMBER`.  Their libbu validators use the same strict
+base-zero integer or finite floating-point spelling accepted by the matching
+typed option and produce a shared range diagnostic.  Use a command-specific
+validator only when its range or error explanation is genuinely
+domain-specific.
+
+When a typed positional role must be stored after schema validation, use
+`bu_cmd_bool_from_str`, `bu_cmd_integer_from_str`, `bu_cmd_hex_integer_from_str`,
+`bu_cmd_long_from_str`, `bu_cmd_hex_long_from_str`, `bu_cmd_number_from_str`, or
+`bu_cmd_char_from_str` instead of adding another `strtol`, `strtod`, or
+first-character reader to the command.  They return nonzero on success and
+leave the destination unchanged on failure, using exactly the native scalar
+grammar.  `BU_CMD_HEX_INTEGER`, `BU_CMD_LONG`, `BU_CMD_HEX_LONG`, and
+`BU_CMD_CHAR` bind the same types to option storage.  `BU_CMD_COUNTING_LONG_FLAG` is the long-counter
+form for repeated flags, and `BU_CMD_VLS_APPEND` appends repeated text values
+to a `bu_vls`, separating nonempty existing content with a space.  These are
+also the appropriate common readers and bindings for a command-owned record
+assembled from several positional roles.
+
+`BU_CMD_CHAR_VALIDATE` and `BU_CMD_VLS_APPEND_VALIDATE` attach a normal
+side-effect-free validator to those storage forms.  `BU_CMD_ISO639_1` uses the
+latter with `bu_cmd_iso639_1_validate` to accept a lower-case ISO 639-1 code;
+`BU_CMD_MAN_SECTION` uses `bu_cmd_man_section_validate` to accept one of the
+BRL-CAD manual-page sections.  Both validators reject input before altering
+the command's storage, unlike the historical callback layering.
+
+Use `bu_cmd_units_from_str` when execution needs the positive conversion
+factor represented by a BRL-CAD unit expression such as `cm`, `in`, or
+`25cm`; it leaves its destination unchanged on failure.  `BU_CMD_UNITS`
+binds a string-valued option with the corresponding
+`bu_cmd_units_validate` preflight, so invalid units are rejected consistently
+by completion, validation, and execution before a command applies its own
+direction of conversion.
+
+=== Canonical keyword values
+
+Use a `bu_cmd_value_keyword` table when a keyword vocabulary needs stable
+canonical spellings, accepted aliases, or per-value descriptions.  Each row
+contains a canonical spelling, an optional null-terminated alias list, and an
+optional description.  `BU_CMD_KEYWORD_VALUES` attaches such a table to a
+keyword option; `BU_CMD_OPERAND_KEYWORD_VALUES` does the same for a positional
+role.
+
+Aliases are accepted during validation and parsing, but static completion
+offers only the canonical spelling.  For a keyword option, parsing also stores
+the canonical spelling in its `const char *` field, so execution does not need
+to duplicate alias normalization.  JSON retains the compatible `values` array
+of canonical spellings and adds `keyword_values`, whose entries include
+`canonical`, `aliases`, and `description`.  A string-valued role may publish
+the same table as completion hints while a validator accepts a wider expression
+grammar; in that case its original string is intentionally retained.
+
+Native schema lint rejects an option or operand that mixes the legacy simple
+keyword array with rich values, and rejects empty or duplicate canonical or
+alias spellings.
+
+=== Optional and shaped values
+
+Every typed `BU_CMD_*` option takes one required scalar argument unless it is
+a flag.  Native schemas may instead declare `BU_CMD_ARG_OPTIONAL` or an
+explicit `bu_cmd_arg_shape` using `BU_CMD_OPTION_SHAPED`.  The shape records
+the token range and one of `scalar`, `token_sequence`, `comma_list`,
+`key_value_list`, `axis_keyed`, `range_pattern`, `rgb`, `color`, `vector3`,
+or `custom`. It is emitted in JSON as `argument_requirement` and
+`argument_shape`, so documentation and completion clients do not need a
+separate mini-language table.
+
+When a `comma_list` role also publishes static keyword values, completion
+matches and replaces only the active list element.  It retains all preceding
+elements and preserves a leading `!` on that element, which supports sort
+forms such as `name,!si` completing to `name,!size`.  String or VLS-backed
+roles may publish this vocabulary as completion guidance without rejecting
+application-defined values such as attribute names.
+
+An optional argument consumes zero or one following token; when supplied, it
+is still checked as the option's declared value type.  This deliberately
+makes a command such as `make_name -s [num]` unambiguous: a following word is
+the optional reset value and is rejected if it is not an integer, rather than
+silently becoming a positional template.
+
+For a multi-token shape, supply a `bu_cmd_value_consume_t` consumer.  It
+receives the complete selected token sequence and the address selected by the
+option's `storage_offset`.  With a null storage pointer it must perform only
+side-effect-free validation; with storage it binds the execution value.
+libbu therefore invokes the same shape parser for execution and incremental
+validation.  A multi-token shape without a consumer is rejected by native
+schema lint.
+
+A positional role whose value has a one-token mini-language may use
+`BU_CMD_OPERAND_SHAPED`.  Its shape is published as the operand's `shape` in
+JSON and must describe exactly one token; the operand's normal cardinality
+still determines how many such tokens the command accepts.  For example, an
+integer-or-inclusive-range operand can use `range_pattern` together with a
+side-effect-free validator, making `100-200` and `100:200` visible as range
+syntax without misrepresenting the role as a plain integer.
+
+=== Declarative command relationships
+
+Use a `bu_cmd_constraint` table for relationships that cannot be represented
+by an individual option or positional role alone.  The compact rows support
+distinct-option counts (such as mutually exclusive modes) and conditional
+operand counts (such as either `-f file` or exactly two object-name operands).
+Options in a row are canonical names without dashes.  `BU_CMD_CONSTRAINT_OPTIONS`
+limits the number of selected options; `BU_CMD_CONSTRAINT_OPERANDS` applies an
+operand range when any, none, or all of its named options are selected.
+
+For new native schemas, attach all command-level properties with
+`BU_CMD_SCHEMA_BOUND`.  Its final four arguments are repeated groups,
+constraints, a structural validator, and a context validator, so those
+independent properties can be used together without positional tail macros:
+
+[source,c]
+----
+static const char *mapping_file_option[] = {"f", NULL};
+static const struct bu_cmd_constraint rename_constraints[] = {
+    BU_CMD_CONSTRAINT_OPERANDS(BU_CMD_CONDITION_ANY_OPTION_PRESENT,
+        mapping_file_option, 0, 0, "-f cannot be combined with object names"),
+    BU_CMD_CONSTRAINT_OPERANDS(BU_CMD_CONDITION_NO_OPTION_PRESENT,
+        mapping_file_option, 2, 2, "source and destination are required"),
+    BU_CMD_CONSTRAINT_NULL
+};
+
+static const struct bu_cmd_schema rename_schema =
+    BU_CMD_SCHEMA_BOUND("rename", "Rename objects", rename_options,
+        rename_operands, BU_CMD_PARSE_OPTIONS_FIRST, NULL,
+        rename_constraints, NULL, NULL);
+----
+
+libbu applies these rows to complete execution parsing and complete
+incremental validation, and publishes them in generated help and JSON.  They
+therefore cannot silently disagree across parsing, validation, and completion.
+
+For a genuinely command-specific side-effect-free syntax rule that cannot be
+expressed as a constraint row, provide a validator in
+`schema.validation.custom_validate`.  The callback receives the token array
+and cursor position and returns a normal `bu_cmd_validate_result`.  It should
+copy the schema, clear `flat.validation.custom_validate`, call
+`bu_cmd_schema_validate` for the ordinary flat rules, then add only its
+command-specific rule.  `bu_cmd_schema_option_present`,
+`bu_cmd_schema_operand_count`, and `bu_cmd_schema_option_span` expose the
+parser's own alias-, cluster-,
+shape-, and `--`-aware interpretation when such a rule depends on a selected
+canonical option or the number of positional operands; do not duplicate an
+option scanner in the command.  Reserve non-flat languages for an explicit
+grammar adapter.
+
+When that additional rule needs host state--for example, a GED database lookup
+to select primitive-specific operations--pass it as the final
+`BU_CMD_SCHEMA_BOUND` argument and call `bu_cmd_schema_validate_ctx`. The callback receives an opaque context
+pointer.  It should copy the schema, clear
+`flat.validation.constraint_data.context_validate`, and call
+`bu_cmd_schema_validate` for the ordinary flat grammar before adding only the
+context-dependent candidates or semantic checks.  libbu itself never
+interprets the context; command hosts choose when to provide it.  This keeps
+one native schema for execution, help, JSON, and completion without reviving
+a parallel metadata table.
+
+`BU_CMD_SCHEMA_EXTERNAL` is reserved for established commands whose executor
+still owns option parsing. It explicitly permits `BU_CMD_*_UNBOUND` metadata
+rows for help and completion; lint rejects such rows in a bound schema. New
+commands should bind directly to an argument record. Native tables are
+non-owning and must have static lifetime. `BU_CMD_ALIASES(...)` and
+`BU_CMD_TREE(...)` shorten common tree declarations.
+
+Positional roles use `BU_CMD_OPERAND`.  Alongside their scalar type they may
+carry an opaque semantic-provider identifier.  libbu preserves that identifier
+without depending on any application; GED uses identifiers such as
+`ged.db_object` and `ged.db_path` to supply database-aware validation and
+completion.  A native schema therefore keeps its library-neutral core while
+still describing application-specific operands precisely.
+
+The compact parser is deliberately for flat option grammars.  Commands with
+subcommands, context-dependent expression languages, or nested commands
+should publish an explicit syntax adapter instead of forcing that grammar into
+option rows.  Its execution parser preserves argv order for options-first and
+stop-at-first-operand forms.  For a flat interspersed-option command,
+`bu_cmd_schema_parse` compacts recognized options and their arguments at the
+front of the caller-owned argv pointer array, preserving positional operand
+order in the remaining suffix; execution can therefore consume the same
+native rows without a second option scanner.  A schema-only option for such a
+command uses
+`BU_CMD_FLAG_UNBOUND`; it participates in help, validation, and completion but
+deliberately refuses `bu_cmd_schema_parse`, which prevents a metadata table
+from silently writing through an invented storage offset.
+
+For conventional flat flag sets, the execution parser and validator accept a
+compact short-option cluster when every member is a no-argument flag: `-ah`
+has the same meaning as `-a -h`.  Attached values and clusters containing an
+option argument remain explicit, avoiding ambiguous getopt-style guessing.
+An optionless schema treats ordinary leading-dash text as an operand, which
+keeps raw commands such as `echo -literal` from inventing an option grammar.
+For a schema with options, a dash-leading integer, long, hexadecimal long, or
+finite-number token is likewise accepted as the next numeric positional role
+(for example, `x -2`) without a preceding `--`; this narrow compatibility rule
+does not apply to string or raw operands, so an unrecognized dash-leading
+string is still reported as an option error.  The standalone `--` marker
+remains available to make every other operand phase explicit.
+
+=== Native command trees
+
+Use `bu_cmd_tree` when a command has a normal root option phase followed by
+named subcommands.  A tree root references its existing `bu_cmd_schema`; each
+`bu_cmd_tree_node` references the existing schema for one child and may supply
+its executor.  The child name and help text come from that schema, so a tree
+does not introduce a second option, help, or completion table.  An optional
+null-terminated alias list adds accepted child spellings without changing the
+canonical child schema name.
+
+`BU_CMD_TREE_NODE` and `BU_CMD_TREE_NODE_NULL` keep static declarations
+compact.  Set the root or node child phase to
+`BU_CMD_TREE_CHILD_AFTER_OPTIONS` when the subcommand follows the parent's
+option phase, or `BU_CMD_TREE_CHILD_FIRST` when it is the first parent
+argument.  Use `BU_CMD_TREE_CHILD_AFTER_FIXED_OPERANDS` for the common
+`command [options] object subcommand` form: the child follows the parent's
+fixed, scalar positional prefix.  This phase deliberately rejects an
+interspersed or variable-width root prefix, so the tree can identify the child
+boundary without guessing whether a word is an operand or a subcommand.  Nodes
+may recursively reference further child arrays; a leaf node normally supplies
+a `bu_cmd_tree_execute_t` callback.  A grammar-only leaf may omit that callback
+when its enclosing command owns execution dispatch.
+
+`bu_cmd_tree_find_subcommand` resolves a direct canonical child or alias.
+`bu_cmd_tree_dispatch` invokes that child's callback and reports dispatch
+failure separately from the callback's command result.  The generic
+`bu_cmd_tree_describe`, `bu_cmd_tree_describe_json`, and `bu_cmd_tree_lint`
+functions derive help, machine-readable structure, and duplicate-name/alias
+checks from the same tree.  A GED grammar adapter should use the tree for its
+subcommand completion, child-schema validation, and analysis rather than
+rebuilding a string list.  `ged_cmd_tree_validate` and
+`ged_cmd_tree_analyze`, declared by `ged/commands.h`, are the public adapter
+entry points for an executable GED grammar.  They recurse through nested node
+arrays, preserving each child schema's option phase, operand validation, and
+semantic token roles.
+
+Some grammars have a parser-owned prefix before the reusable tree, such as an
+object name followed by an operation.  In that case use
+`bu_cmd_tree_validate_argv` after the prefix has been recognized.  Its `argv`
+begins at the tree's root option/child phase (rather than at the root command
+name), and it returns canonical child candidates, aliases, nested validation,
+and `BU_CMD_EXPECT_SUBCOMMAND` exactly as `bu_cmd_tree_dispatch` would
+interpret them.  The prefix adapter remains responsible for adding its token
+offset to the returned result and for any execution setup associated with the
+prefix.  This avoids maintaining a second hard-coded child vocabulary for
+completion or help.
+
+For an `AFTER_OPTIONS` root, a grammar adapter must find the child boundary
+with `bu_cmd_schema_option_span`, not by searching for a word that happens to
+match a child name.  The function uses the schema's own option argument shape,
+so a value such as `--view list` cannot be mistaken for a `list` subcommand.
+
+=== GED registration
+
+An ordinary GED command combines a `bu_opt` builder with positional and
+constraint metadata in `ged_opt_spec`, then uses
+`GED_DECLARE_COMMAND_SET_WITH_OPT_SPEC` and
+`GED_DECLARE_PLUGIN_MANIFEST_WITH_OPT_SPEC`.  Libged translates that compact
+facade to its internal schema engine at registration.  Commands with genuinely
+advanced grammars use `GED_DECLARE_COMMAND_SET_WITH_NATIVE_SCHEMA` or
+`GED_DECLARE_COMMAND_SET_WITH_GRAMMAR`.  Plugin schema metadata is an internal
+interface under active development, so a plugin must be rebuilt with matching
+libged headers rather than relying on a compatibility adapter.
+
+`GED_OPT` is the normal positional facade.  For example,
+`options-first file:file objects:object+` declares an output file followed by
+one or more database objects.  `?`, `*`, `+`, `{n}`, and `{min,max}` express
+cardinality; `keyword(a|b)`, `int(min:max)`, and the positive/nonnegative
+integer and number types cover common value domains.  A semantic provider may
+follow a type as `@provider.name`.  This text is parsed once at command
+registration and the resulting native schema is retained for all subsequent
+validation and completion operations.
+
+Once registered, native schemas participate in `ged_cmd_schema_json`,
+`ged_cmd_validate`, `ged_cmd_complete_result`, `ged_cmd_analyze`, and
+`ged_cmd_schema_lint`.  This makes application frontends such as GSH, MGED,
+and QGED consume the same command metadata without owning separate option
+tables.
+
+=== RGB command values
+
+libbu provides one strict parser for ordinary 8-bit RGB command values.
+`bu_rgb_from_argv` accepts a packed integer triple written as `r/g/b`,
+`r,g,b`, `r;g;b`, or `r g b`, or it accepts three separate argument tokens
+(`r g b`).  Whitespace around a packed delimiter is accepted.  Every channel
+is a base-ten integer from 0 through 255; mixed packed delimiters, partial
+values, decimal values, and trailing text are rejected.  On success the
+function reports whether it consumed one packed token or three channel tokens.
+
+Use `bu_rgb_channel_validate` for command grammars that explicitly expose
+three separate `red`, `green`, and `blue` operands.  The legacy
+`bu_opt_color` reader delegates integer RGB parsing to this API while retaining
+its established packed hexadecimal and normalized floating-point compatibility
+forms for external callers.
+
+For a native command option bound to a `struct bu_color` field, use
+`BU_CMD_RGB`.  It publishes the standard `rgb` argument shape and accepts both
+the one-token and three-token forms.  Its parser determines the actual token
+boundary: a packed color consumes one token and leaves the following operand
+alone, while three separate channels are consumed together.  `BU_CMD_COLOR`
+is the scalar packed-color form when a command intentionally accepts the
+broader `bu_color_from_str` syntax instead.
+
+`BU_CMD_COLOR_COMPAT` is the one-or-three-token native replacement for the
+full `bu_opt_color` value grammar.  It accepts every one-token
+`bu_color_from_str` spelling (including hexadecimal and normalized
+floating-point triples) and also three separate RGB components.  It publishes
+the `color` shape, so a packed value preserves the following operand while an
+unfinished numeric triple is reported as incomplete.  Prefer `BU_CMD_RGB` for
+new 8-bit command colors; use this compatibility form only when a migrated
+command intentionally retains the broader legacy grammar.
+
+For a positional query-or-set color rather than an option binding, use
+`bu_cmd_rgb_optional_validate` for strict 8-bit RGB or
+`bu_cmd_color_optional_validate` for the compatibility grammar.  Both accept
+zero arguments as a query, one packed value, or three separate components;
+they classify a valid unfinished component sequence as incomplete.  After a
+successful validation, `bu_cmd_color_from_argv` converts the accepted one- or
+three-token group without a second local color parser.
+
+New command implementations must use these native helpers rather than
+reintroducing `sscanf`, `strtol`, delimiter checks, range clamps, or bespoke
+RGB completion validators.
+
+=== Three-component vector command values
+
+For an ordinary finite XYZ point or vector, `bu_cmd_vector3_from_argv`
+accepts the corresponding packed forms `x/y/z`, `x,y,z`, and `x;y;z`, a
+single quoted `x y z` argument, or three separate numeric arguments.  All
+components use the native finite-number grammar, so partial values, nonfinite
+values, and trailing text are rejected.  It reports one or three consumed
+tokens and does not alter the output vector on failure.
+
+Use `BU_CMD_VECTOR3` for a native option bound to a `point_t` or `vect_t`
+field.  Its published `vector3` shape lets the parser preserve the operand
+boundary after a packed or quoted vector, consume three separate components
+when supplied, and classify an unfinished separate vector as incomplete for
+completion.  New command implementations should use this shared reader and
+shape instead of `sscanf` or command-local XYZ token scans.
+
+For a common _count x y z_ form, use
+`bu_cmd_counted_vector3_from_argv` and
+`bu_cmd_counted_vector3_arg_shape`.  They accept an integer count followed by
+either one packed vector or three separate components, consuming two or four
+tokens.  The reader keeps the count and vector as separate outputs so a
+command-specific consumer can bind them to its own record without duplicating
+the token-selection or finite-number grammar.
+
+For positional query/set triples, `bu_cmd_vector3_optional_validate` accepts
+zero or one/three vector words; `bu_cmd_vector3_required_validate` is the
+set-only form.  `bu_cmd_integer_pair_optional_validate` provides the matching
+zero-or-two integer pattern.  Commands with a domain range (for example,
+nonnegative screen coordinates) add the appropriate shared scalar validator
+instead of replacing these cardinality helpers with another argv scan.
+
+=== Expression languages
+
+Some commands have a grammar that is not a flat option list.  For example,
+the parser-owned find-style vocabulary of `db_search` is available through
+`db_search_syntax_terms` in `rt/search.h`.  Its terms report argument kinds
+such as ordinary strings, integers, primitive types, and variadic `-exec`
+commands.  Completion clients should use that exported view rather than copy
+the `db_search` parser table.  `db_search_syntax_plan_start` and
+`db_search_syntax_exec_substitution` expose the parser's boundary and `{}`
+substitution rules for the same reason.
+
+GED registers such a command with a `ged_cmd_grammar` adapter rather than
+inventing flat option rows.  The adapter supplies cursor-aware validation,
+whole-line token analysis, JSON description, and lint hooks; the command's
+ordinary GED execution callback remains responsible for execution.  Its JSON
+uses `kind: grammar_adapter` and must describe parser-owned terms from the
+same vocabulary used by execution.  Consequently GSH, MGED, and QGED invoke
+the same adapter through the normal GED completion and analysis APIs without
+special-casing a command name.
@@ -54,6 +54,48 @@ structures and function signatures -- is defined in _raytrace.h_ and the
 headers in the _rt/_ subdirectory, and is documented in the
 Doxygen-generated reference for the LIBRT module.

+== DATABASE PATH ENCODING
+
+`db_full_path_encode()` and `db_full_path_decode()` convert between a
+`struct db_full_path` and its unambiguous, variable-length text representation.
+They are the appropriate APIs for text that will be saved, passed between
+components, or interpreted again as a database path.  `db_full_path_encode()`
+replaces a caller-supplied `bu_vls` only after successful encoding;
+`db_full_path_decode()` similarly replaces an initialized `db_full_path` only
+after successful parsing and database validation.  A failed call leaves its
+output unchanged and returns a `db_full_path_status_t` error code without
+logging a diagnostic for malformed user input.
+
+The canonical representation begins with `/`.  Unescaped `/` separates
+directory entries; literal `/`, `\`, and `@` bytes in an entry name are written
+as `\/`, `\\`, and `\@`, respectively.  A non-root combination member with a
+nonzero instance number is written as an unescaped zero-based `@N` suffix.  For
+example:
+
+[source,text]
+----
+/assembly/bolt.s
+/name\/with\/slashes
+/assembly/member\@name
+/repeat.c/bolt.s@1
+----
+
+`/all.g/child.s` is therefore a hierarchy, whereas `/all.g\/` is the
+single root-level object named `all.g/`.  Empty interior components, a trailing
+unescaped slash, dangling or unsupported escapes, and malformed instance
+suffixes are rejected.  Decoding also verifies that every entry exists and
+that each child is actually a member of the preceding combination.  Boolean
+operation values are reconstructed from the combination tree; they are not
+part of the textual representation.
+
+The older `db_path_to_string()`, `db_path_to_vls()`, and
+`db_string_to_path()` functions retain the historical raw slash-separated
+presentation for API compatibility.  They cannot faithfully distinguish a
+literal slash, backslash, or instance-like `@` suffix from path syntax, and
+new code needing a round trip must use `db_full_path_encode()` and
+`db_full_path_decode()` instead.  Use the legacy functions only at deliberate
+compatibility boundaries where their established raw presentation is required.
+

 [[warning]]
 == WARNING
@@ -200,6 +242,56 @@ ____

 The LIBRT_DEBUG environment variable may be set to the hexadecimal bit vector as described by the DEBUG_* flags listed in the raytrace.h header. Similarly, many LIBRT applications provide a "-x #" command-line option which will take precedence over the environment variable.

+The RT_DEBUG_RTCMP flag (0x10000000) (set with LIBRT_DEBUG=10000000)
+sets up rtcmp capture, but recording starts disabled. Set
+LIBRT_RTCMP_FILE before enabling the flag, then call
+rt_rtcmp_capture_set_enabled(1) from the application or a debugger to
+record selected rays. Call rt_rtcmp_capture_set_enabled(0) to stop
+recording. Enabling returns -1 if the debug flag is unset or the output
+writer failed to initialize; disabling returns 0 even before setup. A
+ray must begin while recording is enabled, and leaving recording
+disabled when it finishes suppresses its record. The debug flag must be
+set before concurrent ray shooting; use the setter to change recording
+state while rays are running.
+
+Captured hits append one high-precision rtcmp JSON record per ray with
+final partitions. Misses produce no record. librt never clears the
+output file; the caller must clear or rotate it before a new comparison
+as needed. Separate processes must not write to the same file
+concurrently. Pending records are flushed within two seconds under
+normal operation and during normal process shutdown; call
+rt_rtcmp_capture_flush() to wait for pending records when using a
+debugger. Disabling recording does not discard records already queued. A
+process terminated abnormally may lose pending records. rtcmp comparison
+files should use the same hit-only capture mode on both sides; its
+generation mode also includes misses. The output can be expanded to also
+include primitive segments if LIBRT_RTCMP_PRIMITIVES is set to 1 before
+capture is set up.
+
+For example, run a single-threaded ray tracing application in a debugger
+and stop at `rt_shootray` for the suspect ray. Capture just that call,
+then compare it with a capture of the same ray from a reference build:
+
+[source,shell]
+----
+$ LIBRT_DEBUG=10000000 LIBRT_RTCMP_FILE=trial.json \
+    gdb --args ./ray_application model.g
+(gdb) break rt_shootray
+(gdb) run
+(gdb) call rt_rtcmp_capture_set_enabled(1)
+(gdb) finish
+(gdb) call rt_rtcmp_capture_set_enabled(0)
+(gdb) call rt_rtcmp_capture_flush()
+(gdb) quit
+$ rtcmp -c reference.json trial.json
+----
+
+Continue to the suspect ray before enabling capture if the breakpoint
+first stops on another ray. Produce `reference.json` with the same ray
+and the same capture mode; set LIBRT_RTCMP_PRIMITIVES=1 for both runs
+when primitive segments are needed to locate a difference before Boolean
+evaluation.
+
 The LIBRT_V4FLIP environment variable may be set to a true or false value to respectively force or disable endianness interpretation of v4 geometry database files. The default behavior is to automatically detect whether flipping the endian interpretation will help LIBRT read a binary-incompatible v4 geometry database file. Setting LIBRT_V4FLIP will override automatic detection.


@@ -2,6 +2,7 @@ if(BRLCAD_EXTRADOCS)
  add_asciidoc("MAN5" STEP.adoc            man5 "" REQUIRED "step-g")
  add_asciidoc("MAN5" attributes.adoc      man5 "" REQUIRED "librt")
  add_asciidoc("MAN5" benchmark.adoc       man5 "" REQUIRED "benchmark")
+  add_asciidoc("MAN5" brlcad-completion.adoc man5 "" REQUIRED "libged")
  add_asciidoc("MAN5" bw.adoc              man5 "" REQUIRED "libicv")
  add_asciidoc("MAN5" cmap.adoc            man5 "" REQUIRED "libdm")
  add_asciidoc("MAN5" dpix.adoc            man5 "" REQUIRED "libicv")
@@ -17,6 +18,7 @@ cmakefiles(
  STEP.adoc
  attributes.adoc
  benchmark.adoc
+  brlcad-completion.adoc
  bw.adoc
  cmap.adoc
  dpix.adoc
@@ -0,0 +1,308 @@
+= BRLCAD-COMPLETION(5)
+:doctype: manpage
+:mansource: BRL-CAD
+:manmanual: BRL-CAD User Configuration
+
+== NAME
+brlcad-completion - configure BRL-CAD command prompt completion behavior
+
+== SYNOPSIS
+
+[source,sh]
+----
+BRLCAD_COMPLETION_MODE=filter|cycle|prefix|legacy|off
+BRLCAD_GSH_COMPLETION_MODE=mode
+BRLCAD_MGED_COMPLETION_MODE=mode
+BRLCAD_QGED_COMPLETION_MODE=mode
+----
+
+== DESCRIPTION
+
+The interactive command prompts in *gsh*(1), *mged*(1), and QGED obtain
+context-sensitive completion candidates from LIBGED.  Candidate generation is
+independent of presentation: the command schema determines which candidates
+are valid, while the command prompt's completion mode determines how pressing
+Tab previews and accepts those candidates.
+
+The default mode is *filter*.  Mode names are case-insensitive.
+
+== MODES
+
+*filter*::
+  Tab previews the first matching candidate and subsequent Tab presses cycle
+  through the remaining matches.  The preview does not replace the user's
+  original seed until it is accepted.  Typing a printable non-space character
+  discards the preview, applies the character to the original seed, and starts
+  the next completion cycle from that refined seed.  If the refined seed has
+  no matches but appending the character to the displayed candidate does, the
+  candidate is accepted and edited instead.  When both interpretations have
+  matches, refining the original seed takes precedence.  Space accepts the
+  preview and begins the next command argument.  Slash accepts a completed
+  database path component and begins the next component.  This is the default.
+
+*cycle*::
+  Tab previews and cycles through candidates.  Editing input accepts the
+  displayed candidate and continues from it.  This resembles Readline menu
+  completion and PowerShell's TabCompleteNext behavior.
+
+*prefix*::
+  Tab inserts the longest prefix shared by all matching candidates.  A later
+  Tab request operates on that more-specific seed.  This resembles traditional
+  shell completion.
+
+*legacy*::
+  Preserve the historical completion interaction of the selected frontend.
+  The exact presentation may differ between GSH, MGED, and QGED.
+
+*off*::
+  Disable context-sensitive command completion.  This does not disable command
+  parsing, validation, or execution.
+
+== KEYS
+
+In *filter* and *cycle* modes, Tab selects the next candidate and Shift-Tab
+selects the previous candidate when the frontend and terminal can distinguish
+Shift-Tab.  Selection wraps at either end of the candidate list.  Space accepts
+the displayed candidate and inserts an argument separator.  Escape cancels an
+active filtering preview and restores the original seed.  Backspace in
+filtering mode removes one visible character from the candidate and confirms
+the text that remains.  This matches ordinary editable-buffer behavior; use
+Escape to discard the whole candidate and restore the original seed.
+
+Characters supplied by the selected candidate but not yet confirmed by the
+user are drawn with a dimmer foreground than the typed seed.  The dim suffix is
+presentation only: it is removed when the candidate is accepted, cancelled, or
+refined, and it is never added to command text sent to LIBGED.  Terminal GSH
+honors *NO_COLOR* and terminal color capability detection, so its dim rendering
+is suppressed when styled output is disabled.
+
+== CANDIDATE DISPLAY
+
+GSH, MGED, and QGED show the candidate set without inserting it into the
+command or command-history text.  The display remains available while Tab and
+Shift-Tab cycle through inline previews, then is removed when completion is
+accepted, cancelled, or refined.  No frontend asks for confirmation before
+displaying a large set.
+
+When every candidate fits within the frontend's available row budget, the
+complete set is arranged in columns.  A larger set is summarized using the
+most specific complete prefix frontier that fits within that budget, for
+example:
+
+[source,text]
+----
+aab (3)  aac (20)  d5m (300)
+----
+
+The parenthesized number in this compact multi-row form is the number of
+matching candidates in that prefix bin.  A long unique candidate may initially
+use its shortest branch prefix, such as `B (1)`, when spelling out its full
+name would prevent the complete frontier from fitting.
+
+If even one bin for every broad prefix cannot fit within the available rows,
+the display falls back to one row containing the most informative
+non-overlapping bins and ends with `... (N more)` so the omitted candidate
+count remains explicit.
+
+The binning is presentation only.  Tab still visits the individual candidates
+in their original order.  GSH, MGED, and QGED derive their row budget from the
+current console height.  They reserve the input row (or rows, for wrapped QGED
+input) and at least one third of the viewport for prior output, allowing
+candidates to use the remaining space, up to two thirds.  The input scrolls
+upward only when the candidate rows need room.
+
+The MGED Tk and QGED consoles insert transient, styled candidate rows into the
+console text itself while keeping those rows outside the command and history
+buffers.  Classic MGED and GSH draw the same rows below their terminal input
+lines.  All presentations erase the rows before the next edit and recompute
+their column layout and row budget when the console is resized.  These visual
+differences do not change the mode semantics.  QGED's legacy mode retains its
+historical completion popup.
+
+== DATABASE PATH SPELLING
+
+Completion and semantic validation use LIBRT's unambiguous database-path
+spelling.  A slash separates hierarchy components.  A literal slash,
+backslash, or at-sign in an object name is written `\/`, `\\`, or `\@`.
+A nonzero repeated-member instance is written as `@N` after a component.
+
+[source,text]
+----
+/assembly/bolt.s       hierarchy: assembly contains bolt.s
+/all.g\/                one object whose name is all.g/
+/assembly/member\@name object name containing @
+/repeat.c/bolt.s@1     second instance of bolt.s in repeat.c
+----
+
+This distinction matters when both a combination named `all.g` and an object
+named `all.g/` exist: `/all.g/child.s` addresses the child of the combination,
+while `/all.g\/` addresses the object with the trailing slash in its name.
+An unescaped trailing slash is not a complete path.
+
+The examples above show the string received by LIBGED.  The command prompt
+may consume a backslash while forming an argument.  In GSH and QGED, type a
+double backslash for each database-path escape, for example
+`draw /all.g\\/`.  In MGED, use a braced Tcl word to preserve the database
+escape, for example `draw {/all.g\/}`; in a Tcl double-quoted word, double the
+backslash instead.  Programmatic callers of `db_full_path_decode()` supply the
+single-backslash spelling shown in the examples.
+
+== LINE-EDITOR COLORS
+
+GSH, MGED, and QGED share an optional semantic line-editor palette.  It
+controls command-line feedback only; it does not replace QGED's application
+theme or MGED's display and color-scheme settings.  Roles omitted from the
+file inherit each frontend's accessible dark- or light-theme defaults.
+
+By default, BRL-CAD reads
+_$XDG_CONFIG_HOME/brlcad/lineedit.json_ when *XDG_CONFIG_HOME* is set, or
+_.config/brlcad/lineedit.json_ beneath the BRL-CAD user configuration
+directory otherwise.  Set *BRLCAD_LINEEDIT_COLORS* to an explicit file to use
+another palette.  Set it to *off* or *none* to suppress user palette loading.
+The palette is read as each frontend starts; restart a frontend after editing
+the file.
+
+The file is a JSON object with version 1 and a *colors* object.  The available
+roles are *command*, *option*, *valid*, *invalid*, *incomplete*, and
+*completion-preview*.  The underscore spelling *completion_preview* is also
+accepted.  A role can be a three- or six-digit RGB hexadecimal value, or an
+object with *color* and *style* members.  *style* is *dim* or *normal*;
+*dim* may also be a Boolean.  A completion preview is dim by default.
+
+[source,json]
+----
+{
+  "version": 1,
+  "colors": {
+    "command": "#75b7ff",
+    "option": "#e9ca4e",
+    "valid": "#48d7d7",
+    "invalid": "#ff6969",
+    "incomplete": "#e178e1",
+    "completion-preview": { "color": "#a0a0a0", "style": "dim" }
+  }
+}
+----
+
+Use *"default"* or *"inherit"* as a role's color to return that role to the
+frontend default.  Unknown role names are ignored for forward compatibility.
+An invalid value for a recognized role rejects the file as a whole, leaves the
+defaults in effect, and produces one startup warning.  GSH maps configured
+colors to ANSI terminal styling and continues to honor *NO_COLOR*; exact
+terminal color fidelity depends on the terminal's color support.  MGED applies
+the same palette to its Tk command prompt, including a blended dim preview,
+and QGED applies it to its console editor.
+
+== SEMANTIC FEEDBACK
+
+GSH, MGED, and QGED use the same LIBGED command schemas that supply completion
+candidates to color command names, options, and semantically checked arguments.
+Invalid and incomplete tokens are distinguished from recognized syntax.  This
+feedback is advisory; command execution remains authoritative.
+
+Within a *search -exec* expression, the prompts treat the words following
+*-exec* as an embedded GED command.  The embedded command name, its
+command-specific options and arguments, `{}` result substitutions, and the
+required standalone `;` terminator are checked independently.  Parsing resumes
+as a search expression after the terminator, allowing subsequent search
+operators to be checked normally.  Tab completion likewise follows the
+embedded command's schema.
+
+Quoted forms such as `"{}"` and `";"` are interpreted with GSH's argv quoting
+rules before semantic checking, matching what GSH and QGED pass to *search*.
+MGED instead parses Tcl syntax before consulting LIBGED: quoted `"{}"` is a
+literal result substitution, braced `{}` is an empty Tcl word, and a bare `;`
+ends the outer Tcl command.  Words containing Tcl variable or command
+substitutions are left unclassified until runtime.  When MGED object-name
+globbing may rewrite a word, that word and subsequent arguments are shown as
+pending rather than being given potentially incorrect validation.
+
+== CONSISTENCY CHECKS
+
+BRL-CAD's automated tests audit completion as a contract rather than checking
+only a hand-written set of command lines.  The registry-wide audit walks every
+discoverable command and subcommand schema in both legacy and new-command
+modes.  Each offered option is inserted using its reported replacement range
+and analyzed again.  Static option-argument candidates are checked in both
+the _--option value_ and _--option=value_ forms.
+
+A second audit mines command examples from the AsciiDoc manual pages.  It
+checks every prefix and replacement range it can construct, then reparses each
+completed command fragment.  A candidate that becomes an unknown or invalid
+token is a test failure.  These checks are intentionally complementary: the
+registry audit covers schemas that are absent from examples, while the manual
+corpus exercises realistic argument order and database paths.
+
+Canonical aliases are suggested only when the schema can parse the canonical
+spelling.  Commands with context-dependent syntax also revalidate each option
+candidate before it is returned, preventing a frontend or compatibility mode
+from advertising an option that its active validator rejects.
+
+== CONFIGURATION
+
+*BRLCAD_COMPLETION_MODE* sets the default for all supporting BRL-CAD command
+prompts.  The frontend-specific environment variables override the global
+variable for one application:
+
+* *BRLCAD_GSH_COMPLETION_MODE*
+* *BRLCAD_MGED_COMPLETION_MODE*
+* *BRLCAD_QGED_COMPLETION_MODE*
+
+GSH also accepts *--completion-mode=mode*.  Its command-line option has highest
+precedence, followed by the GSH-specific environment variable, the global
+environment variable, and finally the *filter* default.
+
+MGED users may set the following in _.mgedrc_.  The _.mgedrc_ value has
+precedence over environment variables and is preserved by MGED's Save Settings
+operation:
+
+[source,tcl]
+----
+set mged_default(completion_mode) filter
+----
+
+QGED provides an exclusive Completion menu.  A choice made there is stored in
+QGED's user settings and has precedence over environment variables on later
+runs.  Delete or change the saved setting to return control to the environment.
+
+Invalid environment or saved-setting values are ignored.  An invalid explicit
+GSH *--completion-mode* argument is reported as an error.
+
+== EXAMPLES
+
+.Use filtering completion in every BRL-CAD prompt
+====
+[source,sh]
+----
+export BRLCAD_COMPLETION_MODE=filter
+----
+====
+
+.Use cycling completion only in MGED
+====
+[source,sh]
+----
+export BRLCAD_COMPLETION_MODE=filter
+export BRLCAD_MGED_COMPLETION_MODE=cycle
+----
+====
+
+.Temporarily start GSH with common-prefix completion
+====
+[source,sh]
+----
+gsh --completion-mode=prefix model.g
+----
+====
+
+== SEE ALSO
+
+*gsh*(1), *mged*(1)
+
+== AUTHOR
+
+BRL-CAD Team
+
+== COPYRIGHT
+
+This software is Copyright (c) 1989-2026 by the United States Government as represented by U.S. Army Research Laboratory.
@@ -141,6 +141,7 @@ set(
  garbage_collect.adoc
  gdiff.adoc
  get.adoc
+  get_bot_edges.adoc
  glob.adoc
  gqa.adoc
  gr.adoc
@@ -306,6 +307,7 @@ set(
  reid.adoc
  release.adoc
  relos.adoc
+  reopen.adoc
  remat.adoc
  repair.adoc
  rfarb.adoc
@@ -381,6 +383,8 @@ set(
  view2model_lu.adoc
  view2model_vec.adoc
  view_func.adoc
+  view_obj_axes.adoc
+  view_obj_polygon.adoc
  viewdir.adoc
  viewsize.adoc
  vnirt.adoc
@@ -17,7 +17,7 @@ adc [-i] subcommand
 [[description]]
 == DESCRIPTION

-This command controls the angle/distance cursor. The *adc* command with no arguments toggles the display of the angle/distance cursor (ADC). The _-i_ option, if specified, causes the given value(s) to be treated as increments. Note that the _-i_ option is ignored when getting values or when used with subcommands where this option makes no sense. You can also control the position, angles, and radius of the ADC using a knob or the knob command. This command accepts the following subcommands:
+This command controls the angle/distance cursor. A subcommand is required. The _-i_ option, if specified before the subcommand, causes applicable value-setting operations to treat their values as increments. It is ignored by query and reset operations. You can also control the position, angles, and radius of the ADC using a knob or the knob command. This command accepts the following subcommands:


 *vars*::
@@ -36,20 +36,20 @@ Set or get angle1 in degrees.
 Set or get angle2 in degrees.


-*dist [distance]*::
+*dst [distance]*::
 Set or get radius (distance) of tick in local units.


-*odist [distance]*::
+*odst [distance]*::
 Set or get radius (distance) of tick (+-2047).


-*hv [position]*::
-Set or get position (grid coordinates and local units).
+*hv [horizontal vertical]*::
+Set or get position using exactly two grid-coordinate values in local units.


-*xyz [position]*::
-Set or get position (model coordinates and local units).
+*xyz [x y z]*::
+Set or get position using exactly three model-coordinate values in local units.


 *x [xpos]*::
@@ -80,8 +80,8 @@ Add to _y_ position (model coordinates and local units).
 Add to _z_ position (model coordinates and local units).


-*anchor_pos [0|1]*::
-Anchor ADC to current position in model coordinates.
+*anchor_pos [0|1|2]*::
+Set or get position anchoring: 0 is free, 1 anchors to model coordinates, and 2 anchors to grid coordinates.


 *anchor_a1 [0|1]*::
@@ -96,16 +96,16 @@ Anchor angle2 to go through anchorpoint_a2.
 Anchor tick distance to go through anchorpoint_dst.


-*anchorpoint_a1[x y z]*::
-Set or get anchor point for angle1 (model coordinates and local units).
+*anchorpoint_a1 [x y z]*::
+Set or get anchor point for angle1 using exactly three model-coordinate values in local units.


 *anchorpoint_a2 [x y z]*::
-Set or get anchor point for angle2 (model coordinates and local units).
+Set or get anchor point for angle2 using exactly three model-coordinate values in local units.


 *anchorpoint_dst [x y z]*::
-Set or get anchor point for tick distance (model coordinates and local units).
+Set or get anchor point for tick distance using exactly three model-coordinate values in local units.


 *reset*::
@@ -144,7 +144,7 @@ Sets angle1 to 37.5 degrees.
 .Get angle1
 [example]
 ====
-mged> **adc a1 37.5**
+mged> **adc a1**

 Gets angle1.

@@ -16,25 +16,25 @@ analyze [options] [subcommand] [subcmd_options]...

 [source]
 ----
-summarize {obj1 [...]}
+analyze [options] summarize obj1 [obj2 ...]
 ----


 [source]
 ----
-intersect [-o output_obj] [-h] {obj1 obj2 [...]}
+analyze [options] intersect [-o output_obj] obj1 obj2 [obj3 ...]
 ----


 [source]
 ----
-subtract [-o output_obj] [-h] {obj1 obj2 [...]}
+analyze [options] subtract [-o output_obj] obj1 obj2 [obj3 ...]
 ----


 [source]
 ----
-inside {obj1} {x} {y} {z}
+analyze [options] inside obj x y z
 ----


@@ -46,14 +46,19 @@ generation capabilities. The classic behavior (and the behavior users
 will see if calling without specifying a subcommand) is a report
 summarizing geometric information about the specified solid(s). This
 behavior may also be explicitly invoked by the *summarize* subcommand.
+Thus, *analyze obj1 [obj2 ...]* is equivalent to
+*analyze summarize obj1 [obj2 ...]*.  The top-level options precede either
+the explicit subcommand or the first object in this shorthand form.

 The *inside* subcommand will take an object and the x y z coordinates
 of a point, and report whether the point is inside or outside the
-object in question (returning 1 if inside and 0 otherwise.)
+object in question (returning 1 if inside and 0 otherwise.)  The point may
+be supplied as three coordinate arguments or as one packed XYZ value using
+the standard BRL-CAD slash, comma, or semicolon separators.

 The *intersect* subcommand will take the first object specified and
 intersect it with any subsequently specified objects - in effect,
-building up a new object with the geoemtry common to all objects
+building up a new object with the geometry common to all objects
 specified.

 The *subtract* subcommand will take the first object specified and
@@ -69,6 +74,11 @@ Print help.
 *-v*, *--verbose*::
 Increase reporting verbosity for the top-level analyze reporting mode.

+The *-h*/*--help* option is also accepted by each explicit subcommand.  The
+*-o*/*--output* option of *intersect* and *subtract* names the object to
+receive the Boolean result; it may appear before, between, or after object
+operands.
+

 [[examples]]
 == EXAMPLES
@@ -254,7 +264,7 @@ point#, (point)
      
 ....

-mged>**analyze subtract -o outside.s pnts.s sph**
+mged>**analyze subtract -o outside.s pnts.s sph.s**


 ....
@@ -10,14 +10,14 @@ bev - Performs the operations indicated in the __Boolean_formula__ and stores th

 [source]
 ----
-bev [-t] [-P#] {new_obj} {Boolean_formula}
+bev [-t] {new_obj} {Boolean_formula}
 ----


 [[description]]
 == DESCRIPTION

-Performs the operations indicated in the __Boolean_formula__ and stores the result in __new_obj__. The __new_obj__ will be stored as an NMG shape (it may be converted to a polysolid by using the *nmg_simplify* command). If the -t option is specified, then the resulting object will consist entirely of triangular facets. The default is to allow facets of any complexity, including holes. The _-P_ option specifies the number of CPUs to use for the calculation (however, this is currently ignored). Only simple __Boolean_formulas__ are allowed. No parentheses are allowed and the operations are performed from left to right with no precedence. More complex expressions must be expressed as BRL-CAD objects using the *r*, *g*, or *c* commands and evaluated using the *facetize* or *ev* commands.
+Performs the operations indicated in the __Boolean_formula__ and stores the result in __new_obj__. The __new_obj__ will be stored as an NMG shape (it may be converted to a polysolid by using the *nmg_simplify* command). If the -t option is specified, then the resulting object will consist entirely of triangular facets. The default is to allow facets of any complexity, including holes. Only simple __Boolean_formulas__ are allowed. No parentheses are allowed and the operations are performed from left to right with no precedence. More complex expressions must be expressed as BRL-CAD objects using the *r*, *g*, or *c* commands and evaluated using the *facetize* or *ev* commands.


 [[examples]]
@@ -21,8 +21,10 @@ The *E* command draws one or more objects using Boolean evaluation. Unlike *draw

 === Options

-*-C r/g/b*::
-Override the display color for all drawn objects using the specified RGB values (each 0–255), separated by `/`.
+*-C* _r/g/b_::
+Override the display color for all drawn objects with 8-bit RGB values.
+Specify the channels as `r/g/b`, `r,g,b`, `r;g;b`, or as three separate
+arguments.  Each channel must be in the range 0–255.

 *-s*::
 Enable shading on the evaluated result display.
@@ -26,7 +26,7 @@ At least one object name must be provided.

 === Options

-*-C r/g/b*::
+*-C* _r/g/b_::
 Override the display color for all drawn objects using the specified RGB triple (each 0–255), separated by `/`. This overrides any color assigned to the objects in the database.

 [[examples]]
@@ -10,14 +10,14 @@ bot - Perform operations on a Bag of Triangles (BoT) primitive.

 [source]
 ----
-bot [-v] [-V] [-C [0-255|0-255|0-255]] {subcommand} {subcommand arguments}
+bot [-h] [-v] [-V] [-C r/g/b] {subcommand} {subcommand arguments}
 ----



 [source]
 ----
-check {degen_faces | extra_edges | flipped_edges | open_edges | solid} {objname}
+check [{degen_faces | extra_edges | flipped_edges | manifold | open_edges | solid}] {objname}
 ----


@@ -31,14 +31,21 @@ chull {input_bot} {output_bot}

 [source]
 ----
-decimate [-f #] [-e #] {input_bot} {output_bot}
+decimate [--help] [-c error] [-n error] [-e length] [-f size] [-t tolerance] {input_bot} [output_bot]
 ----



 [source]
 ----
-extrude {input_bot} {output_bot}
+dump [--help] [-b] [-n] [-F] [-m directory | -o file] [-t dxf|glb|gltf|obj|sat|stl] [-u units] [--materials | --no-materials] [{input_bot} ...]
+----
+
+
+
+[source]
+----
+extrude [--help] [-q] [-R] [-F] [-i | -C] [--max-area-delta ratio] [--min-tri-delta ratio] {input_bot} [output_name]
 ----


@@ -52,7 +59,7 @@ flip {objname}

 [source]
 ----
-get {faces | minEdge | maxEdge | orientation | type | vertices} {objname}
+get {faces | minEdge | maxEdge | orientation | type | thickness | vertices} {objname}
 ----


@@ -66,21 +73,42 @@ isect {objname} {objname2}

 [source]
 ----
-remesh {input_bot} {output_bot}
+info {objname} [F | V] [index_or_range ...]
 ----



 [source]
 ----
-set {orientation | type} {objname} {value}
+pick {objname} {E | F | V} [--first] [px py pz dx dy dz]
 ----



 [source]
 ----
-smooth [-c [0|1|2]] [-d [0|1|2]] [-e #] [-E #] [-I #] {input_bot} {output_bot}
+remesh [--help] [--vdb] [-o output_name] {input_bot} [output_name]
+----
+
+
+
+[source]
+----
+repair [--help] [-p percent] [-a area] [-o output_name] {input_bot} [{input_bot} ...]
+----
+
+
+
+[source]
+----
+set {orientation | type | thickness} {objname} {value}
+----
+
+
+
+[source]
+----
+smooth [--help] [-c [0|1|2]] [-d [0|1|2]] [-e error] [-E error] [-I positive_integer] {input_bot} [output_bot]
 ----


@@ -101,7 +129,7 @@ stat {objname}

 [source]
 ----
-subd [-A [1|2|3|4|5]] [-l #] {input_bot} {output_bot}
+subd [--help] [-A [1|2|3|4|5]] [-l positive_integer] {input_bot} [output_bot]
 ----


@@ -134,6 +162,8 @@ Visualize results when supported by the selected subcommand.

 *-C* _r/g/b_, *--color* _r/g/b_::
 Set the RGB plotting color used by visualization-oriented subcommands.
+The color may be written as _r/g/b_, _r,g,b_, _r;g;b_, or as three separate
+values (_r g b_).


 [[subcommands]]
@@ -141,7 +171,10 @@ Set the RGB plotting color used by visualization-oriented subcommands.


 *check*::
-Performs the requested check on the provided solid. Checks are __degen_faces__, __extra_edges__, __flipped_edges__, __open_edges__, or _solid_. The command will return a 1 (if the specified check finds an issue) or 0.
+Performs a topology or geometry check on the provided BoT. With only an object
+name, *solid* is the default check. The available checks are *degen_faces*,
+*extra_edges*, *flipped_edges*, *manifold*, *open_edges*, and *solid*. The
+command returns 1 when the selected check finds an issue and 0 otherwise.


 *chull*::
@@ -149,21 +182,47 @@ Generates the BoT's convex hull and store it in an object.


 *decimate*::
-Decimates the BoT. The default error metric is Quadric.
+Reduces the BoT triangle count. With no method option it uses GCT with its
+default feature size. Use exactly one method family: GCT (`-f`), classical
+decimation (`-c`, `-n`, and/or `-e`), or simple vertex merging (`-t`).
 +

-*-f #*::
-Specifies the features size (implies use of GCT decimater)
+*-c* _error_, *--max-cord-error* _error_::
+Specifies the maximum chord error for classical decimation.
+
+*-n* _error_, *--max-normal-error* _error_::
+Specifies the maximum normal error for classical decimation.
+
+*-e* _length_, *--min-edge-length* _length_::
+Specifies the minimum edge length for classical decimation.
+
+*-f* _size_, *--feature-size* _size_::
+Specifies the GCT feature size.
+
+*-t* _tolerance_, *--merge-tol* _tolerance_::
+Specifies the simple-decimator vertex merge tolerance.


-*-e #*::
-Specifies the maximum allowed error introduced by decimation (OpenMesh).


+*dump*::
+Exports one or more BoTs to an external mesh file. With no object operands it
+exports all BoTs in the database. Choose at most one of `-m`/`--output-directory`
+and `-o`/`--output-file`, and at most one of `--materials` and
+`--no-materials`. `-t` selects `dxf`, `glb`, `gltf`, `obj`, `sat`, or `stl`;
+the format otherwise follows the output-file extension or defaults to STL.
+`-u` accepts a BRL-CAD unit expression such as `mm`, `cm`, `in`, or `25cm`.
+See *bot_dump*(nged) for format-specific details.
+


 *extrude*::
-Generates an ARB6 representation of the specified plate mode BoT object
+Generates a volumetric BoT or, with `-C`/`--comb`, a CSG tree from the specified
+plate-mode BoT. Normal volumetric output requires an output name unless
+`-i`/`--in-place` is used. CSG output may omit its name and defaults to an
+`_extrusion.r_` combination. `--in-place` and `--comb` are mutually exclusive.
+The simplification ratios accepted by `--max-area-delta` and `--min-tri-delta`
+are in the inclusive range 0 through 1.


 *flip*::
@@ -171,7 +230,22 @@ Flips the BoT triangle normal directions (turns the BoT "inside out"). This will


 *get*::
-Returns the requested parameter of the provided BoT solid. Valid parameters are _faces_, _minEdge_, _maxEdge_, _orientation_, _type_, or _vertices_.
+Returns the requested parameter of the provided BoT solid. Valid parameters are
+_faces_, _minEdge_, _maxEdge_, _orientation_, _type_, _thickness_, or
+_vertices_.
+
+
+*info*::
+Reports BoT summary counts when used with only an object name. Add `F` for face
+information or `V` for vertex information, optionally followed by integer
+indexes, ranges (`first-last` or `first:last`), or separated index lists.
+
+
+*pick*::
+Identifies the BoT edge (`E`), face (`F`), or vertex (`V`) nearest to the
+current viewport ray, or to the explicit six-coordinate ray `px py pz dx dy
+dz`. `--first` chooses the first comparable edge or vertex along the ray; it
+is not valid with face picks.


 *isect*::
@@ -179,35 +253,56 @@ Tests if the two provided BoTs intersect (work in progress).


 *remesh*::
-Creates a new meshed version of the provided object.
+Creates a remeshed version of the provided BoT. If no output name is supplied,
+the input BoT is replaced. Supply the output name either positionally or with
+`-o`/`--output`, but not both. `--vdb` selects the OpenVDB implementation when
+that optional build support is available.
+
+
+*repair*::
+Attempts to repair solid BoTs into manifold geometry. With no output option,
+each input is repaired in place. `-o`/`--output-name` writes a repaired copy
+and consequently requires exactly one input. `-p`/`--max-hole-percent` accepts
+a percentage from 0 through 100; `-a`/`--max-hole-area` supplies a nonnegative
+absolute limit in millimetres.


 *set*::
-Sets the specified property of the provided bot. Properties that can be set are _orientation_ and _type_. Potential values for _orientation_ are none (no), ccw (rh), or cw (lh). Potential values for _type_ are surface, solid, plate, or plate_nocos.
+Sets the specified property of the provided BoT. Properties that can be set are
+_orientation_, _type_, and _thickness_. Potential values for _orientation_ are
+none (no), ccw (rh), or cw (lh). Potential values for _type_ are surface
+(surf), solid (sol), plate, or plate_nocos; _mode_ is accepted as a
+compatibility alias for _type_. Thickness applies only to plate-mode BoTs. Its
+value is either one finite number for every face, or `face_index:number` to set
+one face.


 *smooth*::
-Smooths the BoT using OpenMesh's Jacobi Laplace smoother.
+Smooths the BoT using the Jacobi-Laplace smoother.
 +

-*-c [0|1|2]*::
-Specifies the continuity. The default value is 0, meaning shape is continuous, but not the tangent. A value of 1 means the shape and tangent are continuous, and a value of 2 preserves curvature.
+*-c* _[0|1|2]_, *--continuity* _[0|1|2]_::
+Specifies continuity. The default is 1 (C1), where shape and tangent are
+continuous. A value of 0 selects C0, and 2 selects C2 (which preserves the
+input positions).


-*-d [0|1|2]*::
-Specifies the direction. The default is 0,smoothing in tangential direction. A value of 1 smooths in normal direction, and a value of 2 smooths in both tangential and normal directions.
+*-d* _[0|1|2]_, *--direction* _[0|1|2]_::
+Specifies the component direction. The default is 0, smoothing in the
+tangential direction. A value of 1 smooths in the normal direction, and 2
+smooths in both directions.


-*-e #*::
+*-e* _error_, *--max-local-error* _error_::
 Specifies the max local error.


-*-E #*::
+*-E* _error_, *--max-abs-error* _error_::
 Specifies the max absolute error.


-*-I #*::
-Specifies the iterations for smoothing.
+*-I* _positive_integer_, *--iterations* _positive_integer_::
+Specifies the positive number of smoothing iterations.



@@ -239,11 +334,13 @@ Returns information about the provided BoT.
 Subdivides the provided BoT.
 +

-*-A [1|2|3|4|5]*::
-Specifies the algorithm used to subdivide the BoT. The default is 1 which specifies the loop algorithm. A value of 2 specfies the sqrt3 algorithm, a value of 3 specifies the sqrt3 interpolating algorithm, a value of 4 specifies modified the butterfly algorithm, and a value of 5 specifies the midpoint alorithm.
+*-A* _[1|2|3|4|5]_, *--algorithm* _[1|2|3|4|5]_::
+Specifies the algorithm used to subdivide the BoT. The default is 1, the Loop
+algorithm. A value of 2 selects Sqrt3, 3 selects interpolating Sqrt3, 4
+selects modified Butterfly, and 5 selects Midpoint.


-*-l #*::
+*-l* _positive_integer_, *--level* _positive_integer_::
 Specifies the level of subdivision refinement iterations. Note that the number of triangles generated grows _very_ rapidly with increasing iteration counts - it is recommended that users start with small refinements on the target bot to get a feel for the tradeoff between triangle count and smoothness.


@@ -10,7 +10,7 @@ bot_condense - Used to eliminate unused vertices from a BOT primitive.

 [source]
 ----
-bot_condense {new_bot_primitive} {old_bot_primitive}
+bot_condense [--help] {new_bot_primitive} {old_bot_primitive}
 ----


@@ -19,6 +19,11 @@ bot_condense {new_bot_primitive} {old_bot_primitive}

 Used to eliminate unused vertices from a BOT primitive. It returns the number of vertices eliminated.

+=== Options
+
+*-h*, *--help*::
+Print command help without opening a database.
+

 [[examples]]
 == EXAMPLES
@@ -10,14 +10,14 @@ bot_decimate - Reduces the number of triangles in the __old_bot_primitive__ and

 [source]
 ----
-bot_decimate [-f feature_size] [-c maximum_chord_error] [-n maximum_normal_error] [-e minimum_edge_length] {new_bot_primitive} {old_bot_primitive}
+bot_decimate [--help] [-f feature_size | [-c maximum_chord_error] [-n maximum_normal_error] [-e minimum_edge_length]] {new_bot_primitive} {old_bot_primitive}
 ----


 [[description]]
 == DESCRIPTION

-Reduces the number of triangles in the __old_bot_primitive__ and saves the results to the __new_bot_primitive__. The reduction is accomplished through an edge decimation algorithm. Only changes that do not violate the specified constraints are performed. Specifying the __feature_size__ parameter will result in use of the new GCT decimator (this parameter is mutually exclusive with the other tolerances). The __maximum_chord_error__ parameter specifies the maximum distance allowed between the original surface and the surface of the new BOT primitive in the current editing units. The __maximum_normal_error__ specifies the maximum change in surface normal (degrees) between the old and new surfaces. The __minimum_edge_length__ specifies the length of the longest edge that will be decimated. At least one constraint must be supplied. If more than one constraint is specified, then only operations that satisfy all the constraints are performed.
+Reduces the number of triangles in the __old_bot_primitive__ and saves the results to the __new_bot_primitive__. The reduction is accomplished through an edge decimation algorithm. Only changes that do not violate the specified constraints are performed. Specifying the __feature_size__ parameter selects the GCT decimator and is mutually exclusive with the other tolerances. Alternatively, specify one or more of __maximum_chord_error__, __maximum_normal_error__, and __minimum_edge_length__ to select the classical decimator. The chord-error parameter specifies the maximum distance allowed between the original surface and the surface of the new BOT primitive in the current editing units. The normal-error parameter specifies the maximum change in surface normal (degrees) between the old and new surfaces. The minimum-edge-length parameter specifies the length of the longest edge that will be decimated.


 [[examples]]
@@ -10,7 +10,7 @@ bot_dump - export Bag-of-Triangles (BOT) geometry to a mesh file format

 [source]
 ----
-bot_dump [-b] [-n|--normals] [-F|--full-precision]
+bot_dump [--help] [-b] [-n|--normals] [-F|--full-precision]
         [-m|--output-directory dir] [-o|--output-file file]
         [-t dxf|glb|gltf|obj|sat|stl] [-u unit]
         [--materials|--no-materials]
@@ -34,6 +34,9 @@ Output formats supported:

 === Options

+*-h*, *--help*::
+Print command help without opening a database.
+
 *-b*::
 Write output in binary format where supported (e.g., binary STL, binary glTF/GLB).

@@ -45,16 +48,16 @@ Write full floating-point precision for coordinate values where supported.
 glTF and GLB require standard single-precision coordinates and reject
 this option.

-*-m dir*, *--output-directory dir*::
+*-m*, *--output-directory* _dir_::
 Write each BOT to a separate file in the specified directory `dir`. Mutually exclusive with `-o`.

-*-o file*, *--output-file file*::
+*-o*, *--output-file* _file_::
 Write all output to the single specified `file`. Mutually exclusive with `-m`.

-*-t fmt*::
+*-t* _fmt_::
 Specify the output format type. Accepted values: `dxf`, `glb`, `gltf`, `obj`, `sat`, `stl`. Default is `stl`.

-*-u unit*::
+*-u* _unit_::
 Specify the output units for coordinate values (e.g., `mm`, `cm`, `in`, `ft`). Defaults to the database's native units.

 *--materials*::
@@ -11,15 +11,17 @@ bot_exterior - Reduce a BoT solid to only its exterior (outward-facing) faces.
 [source]
 ----
 bot exterior [options] {input_bot} [output_name]
+bot_exterior [options] {input_bot} [output_name]
 ----


 [[description]]
 == DESCRIPTION

-*bot exterior* analyses a closed solid, non-plate-mode BoT (Bag of Triangles)
-mesh and removes every face that is not classified as exterior, retaining only
-those triangles that belong to the exterior shell.
+*bot exterior* (also available as the standalone *bot_exterior* command)
+analyses a closed solid, non-plate-mode BoT (Bag of Triangles) mesh and
+removes every face that is not classified as exterior, retaining only those
+triangles that belong to the exterior shell.

 === Methods

@@ -10,7 +10,7 @@ bot_face_fuse - Eliminates duplicate faces from a BOT solid.

 [source]
 ----
-bot_face_fuse {new_bot_primitive} {old_bot_primitive}
+bot_face_fuse [--help] {new_bot_primitive} {old_bot_primitive}
 ----


@@ -19,6 +19,11 @@ bot_face_fuse {new_bot_primitive} {old_bot_primitive}

 Eliminates duplicate faces from a BOT solid. It returns the number of faces eliminated.

+=== Options
+
+*-h*, *--help*::
+Print command help without opening a database.
+

 [[examples]]
 == EXAMPLES
@@ -10,7 +10,7 @@ bot_face_sort - Sorts the list of triangles that constitutes the BOT primitive t

 [source]
 ----
-bot_face_sort {triangles_per_piece} {bot_primitive1} [bot_primitive2 bot_primitive3]...
+bot_face_sort [--help] triangles_per_piece bot_primitive1 [bot_primitive2 ...]
 ----


@@ -19,6 +19,13 @@ bot_face_sort {triangles_per_piece} {bot_primitive1} [bot_primitive2 bot_primiti

 Used to sort the list of triangles that constitutes the BOT primitive to optimize it for raytracing with the specified number of triangles per piece. Most BRL-CAD primitives are treated as a single object when a model is being prepared for raytracing, but BOT primitives are normally broken into "pieces" to improve performance. The raytracer normally uses four triangles per piece.

+`triangles_per_piece` must be a positive integer.
+
+=== Options
+
+*-h*, *--help*::
+Print command help without requiring an open database.
+

 [[examples]]
 == EXAMPLES
@@ -10,7 +10,7 @@ bot_flip - Reverse (i.e. flip) all the facet normals within a BOT primitive.

 [source]
 ----
-bot_flip {bot} [bot2 bot3]...
+bot_flip [--help] bot [bot2 ...]
 ----


@@ -21,6 +21,11 @@ Reverse (i.e. flip) all the facet normals within a BOT primitive. When viewing a

 Note: using the *bot_flip* will toggle the orientation of right and left-handed BOT primitives. The orientation of unoriented BOT primitives will not change.

+=== Options
+
+*-h*, *--help*::
+Print command help without requiring an open database.
+
 [[examples]]
 == EXAMPLES

@@ -10,7 +10,7 @@ bot_fuse - fuse duplicate vertices and faces in a BOT mesh

 [source]
 ----
-bot_fuse [-s|-p] new_bot old_bot
+bot_fuse [--help] [-s | -p] new_bot old_bot
 ----


@@ -25,13 +25,17 @@ After fusing, open edges (edges shared by only one face) may be detected. The op

 === Options

+*-h*, *--help*::
+Print command help without requiring an open database.
+
 *-s*::
 Show open edges by drawing them in the display as colored lines after the operation.

 *-p*::
 Plot open edges to a temporary plot file for subsequent inspection.

-Without either flag, open edge detection runs silently and results are not visualized.
+The `-s` and `-p` modes are mutually exclusive.  Without either flag, open
+edge detection runs silently and results are not visualized.

 [[examples]]
 == EXAMPLES
@@ -10,7 +10,7 @@ bot_merge - merge multiple BOT meshes into a single BOT object

 [source]
 ----
-bot_merge bot_dest bot1_src [botn_src ...]
+bot_merge [--help] bot_dest bot1_src [botn_src ...]
 ----


@@ -21,6 +21,11 @@ The *bot_merge* command combines two or more BOT (Bag-of-Triangles) primitive ob

 At least one source BOT must be specified in addition to the destination name.

+=== Options
+
+*-h*, *--help*::
+Print command help without requiring an open database.
+
 NOTE: *bot_merge* concatenates vertex lists without fusing shared vertices. If the input BOTs share vertices at the same position, those vertices will be duplicated in the result. Use *bot_fuse* afterward to merge duplicate vertices.

 [[examples]]
@@ -36,7 +36,7 @@ Note that this command will _not_ (currently) perform any work on plate mode or
 == OPTIONS


-*-a #*::
+*-a* _#_::
 Specify an absolute maximum area in mm for a hole size on which repair will be attempted. Unset by default. Overrides the *p* if specified.


@@ -44,7 +44,7 @@ Specify an absolute maximum area in mm for a hole size on which repair will be a
 Print command help.


-*-p #*::
+*-p* _#_::
 Specify the largest viable hole size for repair as a percentage (0-100) of the mesh area. By default the limit is set to 5 percent. 0 and 100 are interpreted as attempting to fill all holes, which may produce unexpected results. If the *a* is specified it overrides this option.


@@ -10,7 +10,7 @@ bot_smooth - compute and store surface normals in a BOT mesh

 [source]
 ----
-bot_smooth [-t angle_tolerance] new_bot old_bot
+bot_smooth [--help] [-t angle_tolerance] new_bot old_bot
 ----


@@ -25,7 +25,10 @@ NOTE: This command requires the database to be at the current version with suppo

 === Options

-*-t angle_tolerance*::
+*-h*, *--help*::
+Print command help without requiring an open database.
+
+*-t* _angle_tolerance_::
 Maximum angle (in degrees) between adjacent face normals for them to be averaged together. Faces separated by a larger angle produce a hard edge in the normal map. Default is `180.0` (all faces smoothed together).

 [[examples]]
@@ -10,7 +10,7 @@ bot_split - Split a single BOT primitive, containing disjoint groups of facets,

 [source]
 ----
-bot_split {bot} [bot2 bot3]...
+bot_split [--help] bot [bot2 ...]
 ----


@@ -33,6 +33,11 @@ are based on the original BOT name with an available sequential suffix. Object
 attributes are copied to every result, and the result names are listed when
 the command completes.

+=== Options
+
+*-h*, *--help*::
+Print command help without requiring an open database.
+
 [[examples]]
 == EXAMPLES

@@ -10,7 +10,7 @@ bot_sync - Synchronizes the normals of all facets within a BOT primitive so they

 [source]
 ----
-bot_sync {bot} [bot2 bot3]...
+bot_sync [--help] bot [bot2 ...]
 ----


@@ -19,6 +19,11 @@ bot_sync {bot} [bot2 bot3]...

 Synchronizes the normals of all facets within a BOT primitive so they are all in the same direction. When viewing a BOT with the MGED 'e -m1' or 'draw -m1' command, if some of the exterior facets are black and some shaded (red by default), this indicates the black facets have their normal in the wrong direction. To correct this, it is recommended to first run the commands 'bot_vertex_fuse' then 'bot_face_fuse' followed by 'bot_sync'. If the result is all exterior facets are black, then use the MGED 'bot_flip' command to reverse (i.e. flip) all the BOT facet normals. The result should be all exterior facets become shaded.

+=== Options
+
+*-h*, *--help*::
+Print command help without requiring an open database.
+
 [[examples]]
 == EXAMPLES

@@ -10,14 +10,21 @@ bot_vertex_fuse - Used to eliminate duplicate vertices from a BOT solid.

 [source]
 ----
-bot_vertex_fuse {new_bot_solid} {old_bot_primitive>}
+bot_vertex_fuse [--help] new_bot_solid old_bot_primitive
 ----


 [[description]]
 == DESCRIPTION

-Used to eliminate duplicate vertices from a BOT solid. It returns the number of vertices eliminated. No tolerance is used, so the vertices must match exactly to be considered duplicates.
+Used to eliminate duplicate vertices from a BOT solid. It returns the number of
+vertices eliminated. Vertices within the database tolerance are considered
+duplicates.
+
+=== Options
+
+*-h*, *--help*::
+Print command help without requiring an open database.


 [[examples]]
@@ -10,7 +10,7 @@ brep - The *brep* command is the primary means in BRL-CAD for working with NURBS

 [source]
 ----
-brep {obj} [bool | bot | bots | brep | csg | flip | info | intersect | pick | plate_mode | plot | selection | solid | split | shrink_surfaces | tikz | valid] [arguments]
+brep [options] {obj} {bool | bot | bots | brep | csg | dump | flip | geo | info | intersect | pick | plate_mode | plot | repair | selection | solid | split | shrink_surfaces | tikz | topo | valid} [arguments]
 ----


@@ -71,6 +71,10 @@ Generates plotting output for the object using the TikZ plotting language. The o
 *valid*::
 Report if the BRep object is topologically valid.

+*topo*::
+Inspect or edit low-level BRep topology.  This is primarily an advanced
+diagnostic and construction interface.
+
 == OPTIONS

 *-h*, *--help*::
@@ -79,11 +83,30 @@ Print help for the selected *brep* subcommand.
 *-v*, *--verbose*::
 Increase reporting verbosity for subcommands that support additional diagnostic output.

-*-C*, *--color* _r/g/b_::
+*-C*, *--color* _color_::
 Set the color used by subcommands that create plotted or highlighted output.
+The value accepts the normal BRL-CAD color spellings, including packed
+_r/g/b_, _r,g,b_, or _r;g;b_ values, three separate _r g b_ channel words,
+and other scalar color forms accepted by `bu_color_from_str`.

 *--plotres* _#_::
-Set plotting resolution for subcommands that sample curves or surfaces for display output.
+Set a positive plotting resolution for subcommands that sample curves or
+surfaces for display output.
+
+== SUBCOMMAND OPTIONS
+
+*brep* _[--no-evaluation] [--suffix suffix] [output_name]_::
+Convert the selected object to BRep form.  `--no-evaluation` preserves a
+combination as a CSG BRep tree instead of evaluating its booleans; `--suffix`
+sets the naming suffix used for that form.
+
+*split* _[-t thickness] [-o output_object] [-O] [face_indices...]_::
+Create plate-mode BRep output.  Face indices may be individual values, ranges,
+or comma-, slash-, or semicolon-separated lists.  `-O` writes one BRep object
+per face; otherwise `-o` selects the combined output-object root.
+
+*intersect* _other_object first_index second_index [PP|PC|PS|CC|CS|SS]_::
+Calculate the requested component intersection.  `SS` is the default mode.

 == EXAMPLES

@@ -10,7 +10,7 @@ brep plot - Plot specific components of brep objects in a 3D scene.

 [source]
 ----
-brep {obj}plot [C2|C3|E|F|F2d|FSBB|FSBB2d|FTBB|FTBB2d|FTD|I|L|L2d|S|SCV|SK|SK2d|SN|SUV|SUVP|T|T2d|V|CDT|CDT2d|CDTw] [arguments]
+brep {obj} plot [C2|C3|E|F|F2d|FSBB|FSBB2d|FTBB|FTBB2d|FTD|I|L|L2d|S|SCV|SK|SK2d|SN|SUV|SUVP|T|T2d|V|CDT|CDT2d|CDTm2d|CDTp2d|CDTw|CDTn|CDTn2d|CDTnw] [indices ...]
 ----


@@ -21,6 +21,22 @@ If _obj_ is not a brep object, then report that fact and exit. Otherwise, genera

 This command has quite a few subcommands, as it is the primary means in BRL-CAD for visually inspecting properties of BRep objects:

+The optional index arguments select components of the collection associated
+with the operation.  A single index, a comma/slash/semicolon-separated list,
+or an inclusive range (using `-` or `:`) may be supplied.  The component
+collection is operation-specific: `C2` and `C3` select geometric curves, `E`
+selects edges, `L` and `L2d` select loops, `S` and its surface diagnostic
+variants select surfaces, `T` and `T2d` select trims, `V` selects vertices, and
+the face operations (`F*`, `I`, and `CDT*`) select faces.  Omitting indices
+plots the complete collection.
+
+MGED, QGED, and gsh use the selected BRep while completing an index: after a
+plot mode and a space, completion offers only indices present in that
+collection.  A completed numeric index, list element, or range endpoint that
+is outside the selected collection is rejected before plotting.  This check
+is intentionally performed by the `brep` command rather than by a global
+completion rule, so it remains accurate for each object and plot mode.
+

 Plot one or more 2D parametric space geometric curves.

@@ -10,7 +10,7 @@ cat - Displays a brief description of each item in the list of _objects_.

 [source]
 ----
-cat {objects}
+cat object [object ...]
 ----


@@ -35,6 +35,12 @@ object hierarchy and placing the copies in a regular spatial pattern.
 It can produce a simple linear series, a rectangular grid, or radial
 layouts on spherical and cylindrical coordinate systems.

+Where an option takes an XYZ vector, it accepts either three separate
+numbers or one packed value using _x/y/z_, _x,y,z_, or _x;y;z_ notation.
+A quoted _"x y z"_ value is also accepted for Tcl-compatible command
+input.  This applies to *--origin*, *--pivot*, *--dir*, *--translate*,
+*--rotate*, *--atrans*, and *--arot*.
+
 == AXIS-AWARE OPTIONS

 Each pattern publishes a fixed list of axes that any of the four
@@ -52,26 +58,26 @@ becomes the default for every axis whose attribute is otherwise unset)
 or an *AXIS=value* form (which binds to that axis only). All four are
 repeatable; later occurrences override earlier ones.

-*-n, --copies _N_ | _AXIS=N_*::
+*-n*, *--copies* _N_ \| _AXIS=N_::
 Number of copies along the named axis (or every axis when bare).

-*-d, --delta _D_ | _AXIS=D_*::
+*-d*, *--delta* _D_ \| _AXIS=D_::
 Step size between copies along the axis. Degrees for _az_ and _el_;
 model-space distance otherwise.

-*--start _V_ | _AXIS=V_*::
+*--start* _V_ \| _AXIS=V_::
 Starting value for the named axis. Defaults to 0 for non-angular
 axes; defaults to -90° for the _el_ axis (south pole) so that a single
 elevation produces a layer at the equator only when explicitly set.

-*--list _AXIS=v1 v2..._*::
+*--list* _AXIS=v1,v2,..._::
 Provide an explicit list of values for the named axis. Overrides
 *-n*, *-d*, and *--start* for that axis. Only the *AXIS=* form is
 accepted.

 == SPATIAL & ORIENTATION OPTIONS

-*-O, --origin _x y z_*::
+*-O*, *--origin* _x y z_::
 Pattern origin in model space. Per-pattern interpretation:
 +
 *lin*: starting position offset (no-op when 0,0,0). +
@@ -79,13 +85,13 @@ Pattern origin in model space. Per-pattern interpretation:
 *sph*: centre of the sphere. +
 *cyl*: centre of the cylinder base.

-*-p, --pivot _x y z_*::
+*-p*, *--pivot* _x y z_::
 Pivot point baked into each copy when any rotation is applied — that
 is *-r* in *lin*, or *--align* in *sph*/*cyl*. Defaults to the model
 origin (0,0,0). In *lin* mode, this option doubles as the legacy
 rotation centre for *-r* (formerly *--rpoint*).

-*--align _KEYS_*::
+*--align* _KEYS_::
 Comma-separated list of orientation keys. Each copy is rotated so
 that the listed direction(s) follow its position. Valid keys per
 pattern:
@@ -94,7 +100,7 @@ pattern:
 *cyl*: *az* (yaw — also accepts the alias *tan*). +
 *lin*, *rect*: not applicable.

-*--dir _AXIS x y z_*::
+*--dir* _AXIS x y z_::
 Direction vector for the named axis. Defaults:
 +
 *rect*: x → (1,0,0), y → (0,1,0), z → (0,0,1). +
@@ -104,22 +110,25 @@ Direction vector for the named axis. Defaults:

 == HOUSEKEEPING OPTIONS

-*-h, --help*::
+*-h*, *--help*::
 Display help and exit.

-*-i, --increment _#_*::
+*-i*, *--increment* _number_::
 Increment used when generating copy names. The first numeric run found
 in each source name is incremented by this value; if no number is
 present the increment is appended. Default 100.

-*-c, --second-number*::
+*-c*, *--second-number*::
 Move the naming cursor to the _next_ numeric run in object names. May
 be repeated for the third, fourth, etc. number.

-*--depth top|regions|primitives*::
+*--depth* _top_\|_regions_\|_primitives_::
 Controls how deeply the copy hierarchy is constructed. Default is
 *top* for any pattern that produces more than one copy, *primitives*
 for the single-copy linear case.
+
+The short spellings *reg* and *prim* are accepted aliases for
+*regions* and *primitives*, respectively.
 +
 *top* — wrapper combination, source geometry shared. +
 *regions* — every combination down to (and including) the first region
@@ -130,11 +139,11 @@ copied; primitives shared. +
 Before producing the final clone, flatten any matrices that hang
 above the combination members of the source object.

-*-g, --group _name_*::
+*-g*, *--group* _name_::
 Collect the produced clones into a top-level combination called
 _name_.

-*-s, --subs _sstr_ _rstr_*::
+*-s*, *--subs* _sstr rstr_::
 Substitute the first occurrence of _sstr_ with _rstr_ in every
 generated object name.

@@ -143,22 +152,22 @@ generated object name.
 The compact short forms below are accepted only in *lin* mode. They
 exist so that any rel-7-42-2 invocation continues to parse identically:

-*-t, --translate _x y z_*::
+*-t*, *--translate* _x y z_::
 Per-copy translation vector. Equivalent to *--dir step _x y z_ -d step
 |x y z|*.

-*-r, --rotate _x y z_*::
+*-r*, *--rotate* _x y z_::
 Per-copy rotation in degrees about the X, Y, Z axes (in that order).
 Replaced by *--align* in pattern modes.

-*-a, --atrans _n x y z_*::
+*-a*, *--atrans* _n x y z_::
 Total translation _x y z_, split over _n_ copies. Equivalent to *-n n
 -t x/n y/n z/n*.

-*-b, --arot _n x y z_*::
+*-b*, *--arot* _n x y z_::
 Total rotation _x y z_ in degrees, split over _n_ copies.

-*-m, --mirror _axis_ _d_*::
+*-m*, *--mirror* _axis d_::
 Mirror the source about the plane perpendicular to _axis_ (x, y, or z)
 at distance _d_.

@@ -25,35 +25,40 @@ All dimensional parameters are in the current working units unless otherwise not

 === Options

-*-d mean_outer_diameter*::
+*-d* _mean_outer_diameter_::
 Mean outer diameter of the coil. Defaults to 10× the wire diameter if unspecified. If both are zero, defaults to 1000 (with wire diameter defaulting to 100).

-*-w wire_diameter*::
+*-w* _wire_diameter_::
 Diameter of the coil wire. Defaults to 1/10 of the mean outer diameter if unspecified.

-*-H helix_angle*::
+*-H* _helix_angle_::
 Helix angle of the coil in degrees. Affects the pitch of the winding relative to the axis. (Unsupported when `-l` is used.)

-*-p pitch*::
+*-p* _pitch_::
 Distance between adjacent turns along the coil axis. Must be ≥ wire diameter; if smaller, it is automatically set to the wire diameter.

-*-n number_of_turns*::
+*-n* _number_of_turns_::
 Number of full coil turns.

-*-s start_cap_type*::
-End cap style at the start of the coil: `0` = open (no cap), `1` = squared, `2` = squared and ground.
+*-s* _start_cap_type_::
+End cap style at the start of the coil: `0` = open (no cap), `1` = squared,
+`2` = ground, or `3` = squared and ground.

-*-e end_cap_type*::
+*-e* _end_cap_type_::
 End cap style at the end of the coil. Same values as `-s`.

-*-l overall_length*::
+*-l* _overall_length_::
 Constrain the coil to a total axial length. When set, pitch and/or number of turns are adjusted automatically to fit. Caps are forced to open (0) and helix angles are ignored.

 *-L*::
 Use left-hand winding (default is right-hand).

-*-S coil_data_structure*::
-Advanced: provide an explicit section data structure to override the automatic coil generation.
+*-S* _coil_data_structure_::
+Advanced: provide one explicit section as
+`turns,outer_diameter,wire_diameter,helix_angle,pitch,handedness`. Multiple
+`-S` options stack sections in the coil. `handedness` is `1` for right-handed
+and `0` for left-handed winding. This form overrides automatic single-section
+generation.

 [[examples]]
 == EXAMPLES
@@ -19,6 +19,10 @@ color [-e] [low high r g b]

 Creates an entry in the database that functions as part of a color lookup table for displayed regions. The ident number for the region is used to find the appropriate color from the lookup table. The _low_ and _high_ values are the limits of region ident numbers to have the indicated _rgb_ color (0-255) applied. The current list of color table entries may be displayed with the *prcolor* command, and the entire color table may be edited using the _-e_ option and/or using the *edcolor* command. If a color lookup table exists, its entries will override any color assigned using the *mater* command.

+The numeric form requires exactly `low high red green blue`.  The color channels
+are decimal integers from 0 through 255.  The `-e` editing form cannot be
+combined with numeric color-record values.
+

 [[examples]]
 == EXAMPLES
@@ -113,6 +113,12 @@ Conflicts with *-w* and *-f*.
 Use *comb combination lift* for the command form.


+*-d*::
+Decimates the BoT members below an existing combination. This action accepts
+only the combination name and cannot be combined with the other *comb* action
+or region-setting options.
+
+
 *-S*::
 Stop if the combination object already exists.

@@ -25,10 +25,10 @@ With member arguments, it sets the transformation for each listed member, constr

 === Options

-*-i type*::
+*-i* _type_::
 Set the input format type for interpreting transformation data. Affects how the `az el tw x y z sa sx sy sz` parameters are parsed and assembled into a matrix.

-*-r type*::
+*-r* _type_::
 Set the representation type for matrix output when reading.

 === Member specification
@@ -10,7 +10,7 @@ constraint - manage parametric geometric constraints stored on database objects

 [source]
 ----
-constraint set constraint_name key [expression_parts ...]
+constraint set object key [expression_parts ...]
 constraint get constraint_name1 [constraint_name2 ...]
 constraint show constraint_name1 [constraint_name2 ...]
 constraint eval constraint_name1 [constraint_name2 ...]
@@ -27,8 +27,8 @@ Constraints are stored as named attributes on database objects. The *constraint*

 === Subcommands

-*set constraint_name key [expression_parts ...]*::
-Add or update the constraint attribute named `key` on the existing database object `constraint_name`. The expression value is assembled from all remaining arguments `expression_parts`. The `constraint_name` object must already exist in the database.
+*set object key [expression_parts ...]*::
+Add or update the constraint attribute named `key` on the existing database object `object`. The expression value is assembled from all remaining arguments `expression_parts`. The `object` must already exist in the database.

 *get constraint_name1 [constraint_name2 ...]*::
 Print the raw constraint attributes for one or more named objects. Output format per attribute: `object_name attribute_name value`.
@@ -10,7 +10,7 @@ dbot_dump - export currently displayed BOT objects to a mesh file format

 [source]
 ----
-dbot_dump [-b] [-n|--normals] [-F|--full-precision]
+dbot_dump [--help] [-b] [-n|--normals] [-F|--full-precision]
          [-m|--output-directory dir] [-o|--output-file file]
          [-t dxf|glb|gltf|obj|sat|stl] [-u unit]
          [--no-materials]
@@ -34,6 +34,9 @@ All other options are identical to *bot_dump*, including `--no-materials` to exp

 === Options

+*-h*, *--help*::
+Print command help without requiring a display manager.
+
 *-b*::
 Write output in binary format where supported.

@@ -44,16 +47,16 @@ Write per-vertex normals if the output format supports them.
 Write full floating-point precision for coordinate values where supported.
 glTF and GLB reject this option.

-*-m dir*, *--output-directory dir*::
+*-m*, *--output-directory* _dir_::
 Write each BOT to a separate file in the specified directory `dir`. Mutually exclusive with `-o`.

-*-o file*, *--output-file file*::
+*-o*, *--output-file* _file_::
 Write all output to the single specified `file`. Mutually exclusive with `-m`.

-*-t fmt*::
+*-t* _fmt_::
 Specify the output format type: `dxf`, `glb`, `gltf`, `obj`, `sat`, or `stl` (default: `stl`).

-*-u unit*::
+*-u* _unit_::
 Output coordinate units (e.g., `mm`, `cm`, `in`, `ft`).

 [[examples]]
@@ -4,168 +4,109 @@
 :manmanual: BRL-CAD User Commands

 == NAME
-dm - Provides a means to interact with the display manager at a lower level.
+
+dm - Interact with display-manager instances.

 == SYNOPSIS

 [source]
 ----
-dm [-h] [-v] {subcommand} [args]
+dm [-h] [-v] subcommand [args]
+dm attach [--dm name] [--view name] type [name]
+dm bg [color [color]]
+dm debug [level]
+dm get [--dm name] [variable ...]
+dm set [--dm name] [variable [value]]
+dm {width | height | type} [name]
+dm {types | list | initmsg}
 ----

-
 [[description]]
 == DESCRIPTION

-Provides a means to interact with the display manager at a lower level. The *dm* command accepts the following subcommands:
+The *dm* command interacts with display-manager instances at a lower level.
+Top-level options must precede the subcommand. The `-v`/`--verbose` option may
+be repeated to increase report detail.

+The *attach* subcommand creates a display manager of the specified _type_.
+Its optional positional _name_ and `--dm name` name the new manager; supplying
+both with different values is an error. Without a name, a unique name based on
+the manager type is generated. `--view name` associates the manager with an
+existing view. Otherwise it uses the current view when available, or creates a
+view for the manager.
+
+The *bg* subcommand queries the current background without arguments. One
+color sets a solid background; two colors set the two gradient endpoints.
+Colors accept common BRL-CAD forms, including `r/g/b`, `r,g,b`, `r;g;b`, and
+three separate components.
+
+The *debug* subcommand queries or sets the display manager's integer debug
+level. *type*, *width*, and *height* query the selected manager; their
+optional _name_ selects a manager other than the current one. *types* lists
+the display manager types supported by the current build, *list* lists known
+instances, and *initmsg* prints display-manager plug-in initialization
+messages.
+
+The *get* and *set* subcommands query display-manager variables. `dm get`
+and `dm set` with no variable print all variables. `dm set variable` queries
+one variable, while `dm set variable value` assigns it. `dm get variable ...`
+queries each requested variable. `--dm name` selects a manager for either
+subcommand.

 [[options]]
 == OPTIONS

 *-h*, *--help*::
-Print help.
+Print native command-tree help. When followed by a subcommand, print help for
+that child.

 *-v*, *--verbose*::
-Increase top-level command verbosity.
-
-
-*set* _var_ _val_::
-The "set" subcommand provides a means to set or query display manager-specific variables. Invoked without any arguments, the _set_ subcommand will return a list of all available internal display manager variables. If only the _var_ argument is specified, the value of that variable is returned. If both _var_ and _val_ are given, then _var_ will be set to _val_.
-
-
-*size* _width height_::
-The "size" subcommand provides a means to set or query the window size. If no arguments are given, the display manager's window size is returned. If _width_ and _height_ are specified, the display manager makes a request to have its window resized. Note that a size request is just that, a request, so it may be ignored, especially if the user has resized the window using the mouse.
-
-
-*m* _button_ _x y_::
-The "m" subcommand is used to simulate an *M* command. The _button_ argument determines which mouse button is being used to trigger a call to this command. This value is used in the event handler to effect dragging the faceplate scrollbars. The _x_ and _y_ arguments are in X screen coordinates, which are converted to MGED screen coordinates before being passed to the *M* command.
-
-
-*am* [r] [t] [s] _xy_::
-The "am" subcommand effects _mged's_ alternate mouse mode. The alternate mouse mode gives the user a different way of manipulating the view or an object. For example, the user can drag an object or perhaps rotate the view while using the mouse. The first argument indicates the type of operation to perform (i.e., _r_ for rotation, _t_ for translation, and _s_ for scale). The _x_ and _y_ arguments are in X screen coordinates and are transformed appropriately before being passed to the knob command.
-
-
-*adc* [1] [2] [t] [d] _xy_::
-The "adc" subcommand provides a way of manipulating the angle distance cursor while using the mouse. The first argument indicates the type of operation to perform (i.e., _1_ for angle 1, _2_ for angle 2, _t_ for translate, and _d_ for tick distance). The _x_ and _y_ arguments are in X screen coordinates and are transformed appropriately before being passed to the *adc* command (i.e., not "dm adc").
-
-
-*con* [r] [t] [s] [x] [y] [z] _xpos ypos_::
-This form of the "con" subcommand provides a way to effect constrained manipulation of the view or an object while using the mouse. This simulates the behavior of sliders without taking up screen real estate. The first argument indicates the type of operation to perform (i.e., _r_ for rotation, _t_ for translation, and _s_ for scale). The <_x_|_y_|_z_> argument is the axis of rotation, translation, or scale. The _xpos_ and _ypos_ arguments are in X screen coordinates and are transformed appropriately before being passed to the knob command.
-
-
-*con* [a] [x] [y] [1] [2] [d] _xpos ypos_::
-This form of the "con" subcommand provides a way to effect constrained manipulation of the angle distance cursor while using the mouse. This simulates the behavior of sliders without taking up screen real estate. The first argument indicates that this is to be applied to the angle distance cursor. The next argument indicates the type of operation to perform (i.e., _x_ for translate in the _x_ direction, _y_ for translate in the _y_ direction, _1_ for angle 1, _2_ for angle 2, and _d_ for tick distance). The _xpos_ and _ypos_ arguments are in X screen coordinates and are transformed appropriately before being passed to the knob command.
-
-
-*valid* [ogl] [X] [wgl] [rtgl] [...]::
-The "valid" subcommand provides a way to determine if a particular type of display manager (X Windows, OpenGL, etc.) is available - if the display manager type is supported the string denoting that type (X, ogl, etc.) is returned back, otherwise nothing is returned.
-
-
-
+Increase top-level report detail. This option may be repeated.

 [[examples]]
 == EXAMPLES

-The examples show the use of the *dm* command with its various subcommands as presented in the Description section.
+.List the display-manager types available in this build.
+[example]
+====
+mged>**dm types**

-.List the available display manager internal variables.
+Lists available types.
+
+====
+
+.List the current display manager's variables.
 [example]
 ====
 mged>**dm set**

-Lists the available display manager internal variables.
+Prints its internal variables.

 ====

-.Turn on perspective projection in the display using _var_ and _val_ arguments.
+.Set a display-manager variable.
 [example]
 ====
 mged>**dm set perspective 1**

-Turns on perspective projection in the display.
+Sets `perspective` when that variable is supported.

 ====

-.Query the display manager's window size.
+.Set a two-color background gradient.
 [example]
 ====
-mged>**dm size**
+mged>**dm bg 0/0/32 32/32/96**

-The display manager's window size is returned.
+Sets the two background endpoints.

 ====

-.Resize the display manager window.
-[example]
-====
-mged>**dm size 900 900**
-
-The display manager window is resized to 900 x 900.
-
-====
-
-.Simulate a button2 press at specific screen coordinates.
-[example]
-====
-mged>**dm m 2 100 200**
-
-Simulates a button2 press at (100, 200) in X screen coordinates.
-
-====
-
-.Use the alternate mouse mode to rotate an image.
-[example]
-====
-mged>**dm am r 400 100**
-
-Starts an alternate mouse mode rotation at (400, 100).
-
-====
-
-.Start a tick distance manipulation with the mouse.
-[example]
-====
-mged>**dm adc d 300 200**
-
-Starts a tick distance manipulation at (300, 200).
-
-====
-
-.Start a constrained translation down the Z axis using the mouse.
-[example]
-====
-mged>**dm con t z 200 200**
-
-Starts a constrained translation down the Z axis.
-
-====
-
-.Start a constrained tick distance manipulation using the mouse.
-[example]
-====
-mged>**dm con a d 200 100**
-
-Starts a constrained tick distance manipulation.
-
-====
-
-.End the mouse drag.
-[example]
-====
-mged>**dm idle**
-
-Ends the drag.
-
-====
-
-
 [[author]]
 == AUTHOR

 BRL-CAD Team

-
 [[bug_reports]]
 == BUG REPORTS

@@ -4,13 +4,15 @@
 :manmanual: BRL-CAD User Commands

 == NAME
-draw - Adds _objects_> to the display list so that they will appear on the _MGED_ display. The *e* command is a synonym for *draw*.
+draw - Adds _objects_ to the display list so that they will appear on the display. The *e* command is a synonym for *draw*.

 == SYNOPSIS

 [source]
 ----
 draw [-A attribute name/value pairs] [-s] [-A -o attribute name/value pairs] [-C#/#/#] [-L #] [-R] [-S] [-m1] {objects}
+
+draw [--mode 0|1|2|3|4|5] [options] {objects}
 ----


@@ -23,7 +25,7 @@ Adds _objects_ to the display list so that they will appear on the MGED display.
 * The _-C_ option provides the user a way to specify a color that overrides all other color specifications including combination colors and region-id-based colors.
 * The _-s_ option specifies that subtracted and intersected objects should be drawn with shape lines rather than dot-dash lines.
 * The _-A_ option specifies that the arguments provided to this command are attribute name/value pairs, and only objects having the specified attributes and values are to be displayed. The default (without _-o_) is that only objects having all the specified attribute name/value pairs will be displayed. With _-o_, objects that match any of the specified attribute name/value pairs will be displayed.
-* The _-m1_ option will display BOTs shaded if the display manager is OpenGL and the zbuffer and lighting is enabled. To enable these settings, from the MGED GUI, choose "Modes/Display Manager/OpenGL", "Misc/Z-buffer" and "Misc/Lighting". If the zbuffer and lighting is already enabled, toggle them off then back on to ensure they are enabled.
+* The _-m_ or _--mode_ option accepts an integer from 0 through 5. The value may be a separate argument, as in _--mode 1_, joined with an equals sign, as in _--mode=1_, or joined to the short option, as in _-m1_. In QGED and GSH's _--new-cmds_ mode, the meanings are 0 (wireframe), 1 (shaded BoTs, B-Reps, and polysolids), 2 (all solids shaded without evaluating Boolean operations), 3 (wireframe with Boolean operations evaluated), 4 (hidden-line), and 5 (point-sampled triangles). In the legacy MGED and GSH draw implementation, modes 3 and 5 instead mean evaluated shading and evaluated wireframe, respectively. Values outside 0 through 5 are invalid.
 * The _-L_ option allows the user to specify a face count. BoT primitives with more faces than the user set threshold will be represented in wireframe drawing by their bounding boxes rather than the full BoT wireframe.
 * The _-R_ option tells draw to not change the view size when drawing new objects. Without this flag, *draw* will automatically size the view to make the new object(s) visible when the view was previously empty.
 * The _-S_ option tells draw to be "simplified" by skipping subtraction objects when drawing, not drawing NMG interior surfaces, and potentially more. Skipping subtractions is useful in situations where an object has many large objects subtracted from it but those objects have relatively minimal impact on the shape. This results in the default wireframe bearing little resemablance to the evaluated shape.
@@ -10,7 +10,7 @@ edcolor - Puts the user into an editor to edit a file that has been filled with

 [source]
 ----
-edcolor [] []
+edcolor [-E editor]
 ----


@@ -19,6 +19,9 @@ edcolor [] []

 Puts the user into an editor to edit a file that has been filled with the ident-based color lookup table. The entire table may be seen with the *prcolor* command, and entries may be added using the color command. The editor used is whatever the user has set in the environment variable _EDITOR_. If _EDITOR_ is not set, then _/bin/ed_ is used.

+The optional *-E editor* argument selects a specific editor command instead of
+the default.  With no options, *edcolor* opens the default editor.
+

 [[examples]]
 == EXAMPLES
@@ -166,7 +166,7 @@ complete option reference and examples.
 *-x*, *-y*, *-z*::
  Restrict the translation to the specified axis only.

-*-k FROM*::
+*-k* _FROM_::
  Set the reference keypoint.  *FROM* may be an object name or a
  position `x y z`.

@@ -199,13 +199,13 @@ model, and examples.
 *-x*, *-y*, *-z*::
  Restrict the rotation to the specified axis (Euler mode).

-*-k AXIS_FROM*, *-a/-r AXIS_TO*::
+*-k* _AXIS_FROM_, *-a*\|*-r* _AXIS_TO_::
  Supply an explicit axis of rotation (axis mode).

-*-c CENTER*::
+*-c* _CENTER_::
  Set the pivot center (defaults to bounding-box center).

-*-O ANGLE_ORIGIN*, *-d DEGREES*::
+*-O* _ANGLE_ORIGIN_, *-d* _DEGREES_::
  Set the angle origin and explicit rotation angle.

 .Quick examples
@@ -229,14 +229,14 @@ Scales the object by a uniform or per-axis factor.  See
 *edit scale*(nged) for the complete option reference, the SCALE
 reference-frame model, and examples.

-*-k FROM*::
+*-k* _FROM_::
  Reference "from" position.  Defaults to the object keypoint.

-*-a TO*, *-r TO*::
+*-a* _TO_, *-r* _TO_::
  "To" position (absolute or relative).  Together with *-k*, defines
  the reference scale vector.

-*-c CENTER*::
+*-c* _CENTER_::
  Center of the scaling operation.

 .Quick examples
@@ -10,9 +10,7 @@ editit - open a file in an external text editor

 [source]
 ----
-editit [opts] <filename>
-editit -f <file>
-editit -e <editstring> <filename>
+editit [-e editstring] (-f file | file)
 ----


@@ -21,14 +19,15 @@ editit -e <editstring> <filename>

 The *editit* command opens a file in an external text editor. The editor used is determined by the current environment (typically the `EDITOR` environment variable or a system default).

-The file to edit can be specified as a positional argument or via the `-f` option. Only one file specification is allowed per invocation.
+The file to edit can be specified as a positional argument or via the `-f`
+option. Exactly one file specification is required per invocation.

 === Options

-*-f file*::
+*-f* _file_::
 Specify the file to edit. Equivalent to providing `filename` as a positional argument.

-*-e editstring*::
+*-e* _editstring_::
 Specify an edit string to pass to the editor (deprecated; prefer specifying the editor via the environment).

 [[examples]]
@@ -10,14 +10,19 @@ edmater - Places the user in an editor ready to edit a file filled with shader a

 [source]
 ----
-edmater {combinations} []
+edmater [-E editor] {combination} ...
 ----


 [[description]]
 == DESCRIPTION

-Places the user in an editor ready to edit a file filled with shader arguments for the combinations listed on the command line. The arguments placed in the file for editing are the _shader_ name and its own arguments, RGB color,__RGB_valid__ flag, and the inheritance flag. The editor used is whatever the user has set in the environment variable _EDITOR_. If _EDITOR_ is not set, then _/bin/ed_ is used.
+Places the user in an editor ready to edit a file filled with shader arguments
+for the combinations listed on the command line. The arguments placed in the
+file for editing are the _shader_ name and its own arguments, RGB color,
+_RGB_valid_ flag, and the inheritance flag. By default the editor is selected
+by the environment variable _EDITOR_, or _/bin/ed_ when it is unset. The
+optional `-E editor` argument supplies the editor command for this invocation.


 [[examples]]
@@ -10,20 +10,43 @@ env - Print the current environmental variables.

 [source]
 ----
-env
+env [options] [pattern ...]
+env get variable
+env set variable value
 ----


 [[description]]
 == DESCRIPTION

-Print the current environmental variables.
+Without a subcommand, *env* lists the BRL-CAD environment variables that are
+currently set.  Optional shell-style patterns limit the listed variable names.
+
+*env get* reports one known variable's current value.  *env set* changes one
+known variable for the current process and reports the new value.
+
+== OPTIONS
+
+*-h*, *--help*::
+Print command usage.
+
+*-A*, *--all*::
+List known variables even when they are not set.
+
+*-S*, *--system*::
+Include known variables used by external system or third-party software.
+
+*-C*, *--context*::
+Show the BRL-CAD library or executable associated with each listed variable.
+
+*-M*, *--memory*::
+Report the current memory totals and page size instead of listing variables.


 [[examples]]
 == EXAMPLES

-Print the current environmental variables.
+List variables associated with BRL-CAD:

 .Enter *env* to display the current environmental variables.
 [example]
@@ -32,6 +55,9 @@ Print the current environmental variables.
 mged> **env**::
 The current environmental variables and their values are displayed.

+mged> **env --all BRLCAD_***::
+All known BRL-CAD-prefixed variables are listed, including unset ones.
+


 ====
@@ -14,6 +14,7 @@ erase object [object ...]
 erase -r object [object ...]
 erase -A attr value [attr value ...]
 erase -o -A attr value [attr value ...]
+erase [--view name] [--mode number] object [object ...]
 ----


@@ -33,6 +34,11 @@ objects are erased from the display. By default all specified pairs must match;
 the *-o* option changes attribute mode so that matching any one of the supplied
 pairs is sufficient.

+In the new command form used by QGED and other view-aware clients, *--view*
+selects an independent view and *--mode* limits erasure to a drawing mode.
+Those options are not available in the legacy command form; conversely, the
+legacy *-r*, *-A*, and *-o* modes are not available in the new command form.
+

 [[examples]]
 == EXAMPLES
@@ -10,7 +10,7 @@ facetize - Creates __new_object__ using __old_object__ as a guide, creating an e

 [source]
 ----
-facetize [-h] [-v] [-q] [-n] [-r] [-s suffix] [-p prefix] [--in-place] [--max-time #] [--max-pnts #] [--resume] [--methods m1,m2,...] [--method-opts METHOD opt1=val opt2=val...] [--no-empty] [--log-file filename] [--nmg-booleval] [--disable-fixup] [--perturb] [--no-perturb] [--perturb-sa-tol #] [--perturb-vol-tol #] [--tolerate-failures] [-B -t threshold] {old_object new_object}
+facetize [-h] [-v] [-q] [-n] [-r] [-j jobs] [-s suffix] [-p prefix] [--in-place] [--max-time #] [--max-pnts #] [--resume] [--methods m1,m2,...] [--method-opts "METHOD opt1=val opt2=val..."] [--no-empty] [--log-file filename] [--nmg-booleval] [--disable-fixup] [--perturb] [--no-perturb] [--perturb-sa-tol #] [--perturb-vol-tol #] [--tolerate-failures] [-B -t threshold] {old_object new_object}
 ----


@@ -45,6 +45,8 @@ By default, the Manifold BoT path can make use of a coplanarity-avoidance pertur

 When the perturbation step is active, per-region *facetize* validates the initial Boolean output against the original CSG geometry using a Crofton stochastic raytrace. The default tolerance thresholds that trigger a perturb retry are 10% for both surface area and volume; these can be adjusted with *--perturb-sa-tol* and *--perturb-vol-tol*. At the end of a per-region facetization run *facetize* prints a concise validation summary listing how many regions passed, triggered a perturb retry, or encountered one of the following noteworthy conditions:

+_Unbounded halfspace (validation unavailable)_: Crofton surface-area and volume comparisons require a finite sampling domain. A standalone halfspace, or another CSG result without finite bounds, is therefore not sampled and is counted as having validation unavailable. A bounded object intersected with or subtracted by a halfspace can still be validated because its finite operand supplies the sampling bounds.
+
 _Sub-mm / few-hit bypass (accepted with note)_: When the Crofton sampler finds only a very small number of ray-surface intersections (below an internal threshold of 50 crossings), the sampling noise alone would exceed 14% relative error, making any SA comparison meaningless. Geometry in this category is typically sub-millimetre in cross-section (e.g., a TGC with a radius under 0.2 mm) but the stochastic sampler has confirmed that some geometry is present. The BoT conversion is accepted and the region is counted separately in the summary. Users should verify that such extreme geometry reflects actual modeling intent rather than an accidental near-degenerate primitive.

 _Zero-hit replacement_: When the Crofton sampler fires rays but records zero intersections with the CSG geometry while the corresponding BoT is non-empty, *facetize* concludes that the Boolean evaluation most likely produces empty geometry (for example, a subtractor that fully engulfs the base object). In this case the non-empty BoT is discarded and replaced with an empty BoT to match the expected raytrace behavior. If this replacement appears unexpected for a given region, the *lint* command can be used to inspect the result.
@@ -61,44 +63,56 @@ Different tolerance settings will create finer or coarser meshes. See the *tol*

 Primitive tessellation is performed in a child process against a private working copy of the database in the BRL-CAD cache.  The original database is not modified as individual primitive meshes are generated.  Only after the conversion succeeds are the requested results transferred from the working database.  This separation also permits an interrupted conversion to retain its intermediate state for use with *--resume*.

-The parent command sends primitive names to a persistent tessellation process one at a time.  The child reports a result for each name, so a timeout, conversion failure, or child-process crash that occurs before a database write can be associated directly with the affected primitive.  The child is restarted when necessary and processing continues with the next name; the parent does not subdivide and retry the whole group to discover which object failed.  Unless output is suppressed with *--quiet*, long tessellation batches also report their current object and completed-object count at approximately five-second intervals.
+The parent command sends primitive names to a small pool of persistent tessellation processes.  Each child reports a result for every name, so a timeout, conversion failure, or child-process crash can be associated directly with the affected primitive.  A child is restarted when necessary and processing continues with the next name; the parent does not subdivide and retry the whole group to discover which object failed.  Unless output is suppressed with *--quiet*, long tessellation batches also report their completed-object count and active-worker state at approximately five-second intervals.

-Database updates use a separate write handshake.  After preparing a mesh in memory, the child announces that it is ready to write and reports the approximate mesh size, then waits.  The parent acknowledges that it is waiting for the write before the child may update the working database.  The child explicitly reports when the update is complete.  Consequently, the normal per-object tessellation limit, including *--max-time* and method-specific limits, applies to mesh preparation and does not interrupt an acknowledged database write.
+By default, *facetize* uses at most two worker processes and only enables the second when both CPU and memory information indicate it is safe.  It reserves the larger of one GiB or one quarter of total physical memory for the rest of the system.  Starting another job also requires at least 512 MiB beyond that reserve, or the largest worker resident-memory measurement seen so far if that is greater.  If the platform cannot report the required memory information, *facetize* falls back to one worker.  The available CPU count is divided among worker processes and is also imposed as the thread limit inside each worker, preventing nested algorithms from independently using all CPUs.  *--jobs* changes the maximum process count; it does not bypass the memory admission checks.
+
+Per-region BoT conversion uses this worker policy for both independent CSG validation and initial Manifold Boolean evaluation.  When more than one worker is available, persistent validation processes each open their own read-only handle to the original database and compute Crofton surface-area and volume references for different regions.  Persistent Boolean processes then evaluate different region trees using independent read-only handles to one shared snapshot of the tessellated working database.  That snapshot also serves as the rollback checkpoint, so increasing *--jobs* does not create additional full database copies.  This process isolation avoids sharing mutable raytrace preparation or database state between concurrent evaluations.  Each result remains associated with the requested region name.  The parent commits completed BoTs through one writer and continues to perform hierarchy changes, validation decisions, and any perturb retries serially.  A one-worker run retains the established in-process order and avoids the snapshot phase.
+
+Validation and Boolean workers report their completed-region count and active-worker state approximately every five seconds.  When *--max-time* is specified, it also bounds each parallel CSG reference or Boolean request; a timed-out process is terminated, and the failure is associated with that region.  Failure or timeout of supplementary CSG validation does not cause unrelated regions to be retried.
+
+Database updates use a separate write handshake.  After preparing a mesh in memory, a child announces that it is ready to write and reports the approximate mesh size and its current resident memory, then waits.  The parent grants write permission, the child acknowledges when it is starting the write, and the child explicitly reports when the update is complete.  Consequently, the normal per-object tessellation limit, including *--max-time* and method-specific limits, applies to mesh preparation and does not interrupt an acknowledged write.
+
+With multiple workers, primitive tessellation children write to small staging databases rather than modifying the shared working database.  Region Boolean children read one immutable cache-local snapshot while completed results are committed to the working database.  The snapshot doubles as the recovery checkpoint and is opened independently by each worker; it is not duplicated per worker.  For very large files, snapshot preparation reports the amount copied and elapsed time at five-second intervals.  A region result is first completed in memory and enters the write handshake only when it is ready to replace the prior staged result.  After a child reports a completed staging write, the parent submits that result to a single persistent writer process.  The writer announces that it is ready, waits for the parent's permission, acknowledges that it is starting the write, transfers the result through one persistent working-database handle, and reports completion.  This permits tessellation and initial region Boolean evaluation to proceed in parallel without concurrent database allocation updates or repeated full directory scans, while allowing the parent to supervise the canonical database write itself.  With one worker, the established direct path avoids the extra staging I/O and database snapshot.

 Before the first primitive conversion, the parent measures write throughput on the same cache filesystem as the working database.  It writes a temporary file in 1 MiB chunks until approximately one second has elapsed or 128 MiB has been written, then removes the file immediately.  Successful mesh writes of at least 1 MiB subsequently refine this profile.  For each database update, the parent allows ten times the projected write time, with a minimum of five seconds and a maximum of five minutes.  This measured allowance protects legitimate long writes on slow storage while still detecting a genuinely stalled update.

-If a child fails before write permission is granted, the working database is known to be unchanged and no rollback is needed.  A failure, crash, or write-deadline expiration after permission is granted but before completion is ambiguous: the working database may contain a partial update.  In that case *facetize* restores its cache-local checkpoint and replays only the primitive conversions already known to have succeeded.  The original database remains untouched during this recovery.
+If a child fails before acknowledging that its write has started, the working database is known to be unchanged and no rollback is needed.  In parallel mode, a failure during a child write affects only that worker's disposable staging database, so the failed object is reported and the worker can be restarted without replaying unrelated objects.  A serial child failure during a direct write, or a writer-process failure after acknowledging write start, is ambiguous because the working database may contain a partial update.  In those cases *facetize* restores its cache-local checkpoint and replays only the conversions not already tied to a specific failure.  The original database remains untouched during this recovery.


 [[facetize_options]]
 == Options


-*-h, --help*::
+*-h*, *--help*::
 Print help and exit.


-*-v[v..], --verbose*::
+*-v*, *--verbose*::
 Prints extra (verbose) information in results. May be overridden by the *--quiet* flag.


-*-q, --quiet*::
+*-q*, *--quiet*::
 Suppress all output (overrides verbosity flag.)


-*-n, --nmg-output*::
+*-n*, *--nmg-output*::
 Instructs *facetize* to produce NMG solids rather than BoT solids.


-*-r, --regions*::
+*-r*, *--regions*::
 Rather than converting all specified inputs to one top level object, walk specified trees and individually convert regions to facetized objects. This mode is useful when wanting to display models in shaded mode while preserving color and region ID properties. If no regions are present a normal conversion is performed instead.


-*-s, --suffix*::
+*-j, --jobs #*::
+Set the maximum number of facetize worker processes. A value of 1 forces serial processing. The default value of 0 selects a conservative automatic limit based on available CPUs and memory. Memory checks may delay or reduce parallel work even when a larger value is requested. In per-region BoT mode the same limit controls parallel CSG reference sampling and initial Manifold Boolean evaluation.
+
+
+*-s*, *--suffix* _suffix_::
 User specified suffix to use avoiding naming conflicts (naming conflict avoidance is needed when creating objects in *-r* mode.)


-*-p, --prefix*::
+*-p*, *--prefix* _prefix_::
 User specified prefix to use avoiding naming conflicts (naming conflict avoidance is needed when creating objects in *-r* mode.)


@@ -106,11 +120,11 @@ User specified prefix to use avoiding naming conflicts (naming conflict avoidanc
 Replace the specified object(s) with their facetizations. (WARNING: this option is destructive and will change pre-existing geometry!)


-*--max-time #*::
+*--max-time* _seconds_::
 Maximum time to spend per object (in seconds). Default is method specific. Note that specifying shorter times may cut off conversions (particularly using sampling methods) that could succeed with longer runtimes. Per-method time limits can also be adjusted to allow longer runtimes on slower methods.


-*--max-pnts #*::
+*--max-pnts* _count_::
 Maximum number of pnts per object to use when applying ray sampling methods.


@@ -118,19 +132,19 @@ Maximum number of pnts per object to use when applying ray sampling methods.
 Resume an incomplete facetization process (will utilize cached data from a previous run rather than starting from scratch.) Re-running without this option will clear any old data and start from the beginning.


-*--methods*::
-Accepts a comma separated list of one or more facetization methods to use. The default is to try all algorithms available as needed, but if a user knows they want to try a specific methodology they can call it out using this option.
+*--methods* _method[,method...]_::
+Accepts a comma separated list of one or more facetization methods to use. The default tries NMG tessellation first, Manifold Dual Contouring (MDC) second, and SPSR as a final fallback. Other listed methods may be selected explicitly if a user wants to try a specific methodology.


-*--method-opts*::
-This option can be used to pass parameter values to specific facetize methods. The argument format is "METHOD opt1=val1 opt2=val2 ...". See the *--help* output for which methods and parameters are supported by *facetize*.
+*--method-opts* _"METHOD option=value ..."_::
+This option can be used to pass parameter values to specific facetize methods. Its complete argument must be quoted: *--method-opts "METHOD opt1=val1 opt2=val2 ..."*. Each setting is a *key=value* pair. See the *--help* output for which methods and parameters are supported by *facetize*.


 *--no-empty*::
 Do not write out empty BoT objects when a Boolean evaluation results in an empty mesh.


-*--log-file*::
+*--log-file* _file_::
 Specify a log file in which to store the full verbose output of a facetization process. This is recommended for large or long running facetize runs to allow users to better understand what steps were taken and what problems might have arisen.


@@ -148,10 +162,10 @@ Enable the coplanarity-avoidance perturbation step. In per-region mode this beha
 *--no-perturb*::
 Disable the coplanarity-avoidance perturbation retry machinery in BoT Manifold Boolean evaluation. This option conflicts with *--perturb*.

-*--perturb-sa-tol #*::
+*--perturb-sa-tol* _percent_::
 Surface-area percentage threshold (0–100) that triggers the coplanarity-avoidance perturb retry when the per-region Crofton-sampled CSG surface area differs from the initial facetized BoT surface area by more than this amount. Default is 10 (percent).

-*--perturb-vol-tol #*::
+*--perturb-vol-tol* _percent_::
 Volume percentage threshold (0–100) that triggers the coplanarity-avoidance perturb retry when the per-region Crofton-sampled CSG volume differs from the initial facetized BoT volume by more than this amount. Default is 10 (percent).

 *--tolerate-failures*::
@@ -231,21 +245,15 @@ mged>**facetize --tolerate-failures large_model large_model.partial.bot**

 ====

-.Increase Decimation in CM Mode
+.Refine a Manifold Dual Contouring conversion
 [example]
 ====
-mged>**facetize --methods CM --method-opts feature_size=0.06 d_feature_size=2.0 ellipse.r ell.bot**
+This selects MDC directly and requests a finer cell size with a larger ray
+budget than the default:

-The default settings on this object in CM mode will produce a little over 8000 faces in the final bot, but the addition of the *d_feature_size* option with a >1.5 value has dramatically reduced the count to 104.
+mged>**facetize --methods MDC --method-opts "MDC feature_size=0.1 max_rays=400000" ellipse.r ell.bot**

-====
-
-.Decrease Decimation in CM Mode
-[example]
-====
-mged>**facetize --methods CM --method-opts feature_size=0.06 d_feature_size=0.01 ellipse.r ell.bot**
-
-If the intent is preserve a more detailed mesh, reducing *decimation-feature-size* will keep more of the original triangles - in the above example, almost 250 thousand of the original 6.9 million faces were retained. NOTE: use lower values here cautiously, as extremely large meshes can be very difficult for many tools to deal with.
+Smaller feature sizes increase mesh detail, ray count, memory use, and runtime.

 ====

@@ -22,9 +22,9 @@ The available options are:

 * *-c* : Crunch the colormap (apply colormap to pixel values).
 * *-i* : Inverse mapping (draws the image upside down).
-* *-s squaresize* : Sets both the output width and height to the specified `squaresize`.
-* *-w width* : Sets the output width.
-* *-n height* : Sets the output height.
+* *-s squaresize* : Sets both the output width and height to the specified positive `squaresize`.
+* *-w width* : Sets the output width to a positive value.
+* *-n height* : Sets the output height to a positive value.
 * *-h* or *-?* : Prints the command usage and exits.

 If size parameters are omitted, it defaults to capturing a 512x512 region.
@@ -10,7 +10,7 @@ find - find all references to objects

 [source]
 ----
-find [-a] <objects>
+find [-a] object [object ...]
 ----

 [[description]]
@@ -10,7 +10,7 @@ find_bot_edge - find and identify a BOT (Bag of Triangles) edge

 [source]
 ----
-find_bot_edge bot "view_x view_y view_z"
+find_bot_edge [--help] bot "view_x view_y view_z"
 ----

 [[description]]
@@ -18,6 +18,11 @@ find_bot_edge bot "view_x view_y view_z"

 The *find_bot_edge* command searches a BOT (Bag of Triangles) primitive and identifies the edge that is closest to a given view coordinate. 

+=== Options
+
+*-h*, *--help*::
+Print command help without requiring an open database or active view.
+
 If successful, the command returns two integers:
 1. The numeric ID of the first vertex (`vi1`) forming the edge.
 2. The numeric ID of the second vertex (`vi2`) forming the edge.
@@ -10,7 +10,7 @@ find_bot_pnt - find and identify a BOT point

 [source]
 ----
-find_bot_pnt bot "view_x view_y view_z"
+find_bot_pnt [--help] bot "view_x view_y view_z"
 ----

 [[description]]
@@ -18,6 +18,11 @@ find_bot_pnt bot "view_x view_y view_z"

 The *find_bot_pnt* command searches a BOT (Bag of Triangles) primitive and identifies the vertex that is closest to a given view coordinate. 

+=== Options
+
+*-h*, *--help*::
+Print command help without requiring an open database or active view.
+
 If successful, the command returns a single integer representing the numeric ID of the closest vertex.

 The arguments are:
@@ -44,7 +44,7 @@ The example shows the use of the *garbage_collect* command to delete unused spac
 [example]
 ====

-mged> **garbage_collect**:: -c
+mged> **garbage_collect -c**
 Cleans out unused space in the database.


@@ -10,7 +10,7 @@ get - Retrieves parameter values of database objects.

 [source]
 ----
-get {object_name_pattern} [param_name]
+get object_or_path [property]
 ----


@@ -0,0 +1,37 @@
+= GET_BOT_EDGES(nged)
+:doctype: manpage
+:mansource: BRL-CAD
+:manmanual: BRL-CAD User Commands
+
+== NAME
+
+get_bot_edges - list the edges of a BOT primitive
+
+== SYNOPSIS
+
+[source]
+----
+get_bot_edges [--help] bot
+----
+
+== DESCRIPTION
+
+The *get_bot_edges* command lists the unique edges of a BOT (Bag-of-Triangles)
+primitive. Each edge is written as a pair of vertex indices.
+
+=== Options
+
+*-h*, *--help*::
+Print command help without requiring an open database.
+
+== SEE ALSO
+
+*find_bot_edge*(nged), *find_bot_pnt*(nged)
+
+== AUTHOR
+
+BRL-CAD Team
+
+== BUG REPORTS
+
+Report bugs and problems to devs@brlcad.org.
@@ -4,57 +4,77 @@
 :manmanual: BRL-CAD MGED Commands

 == NAME
-graph - Used to query and manipulate properties of the graph that corresponds to the currently opened .g database.
+
+graph - generate a database hierarchy graph

 == SYNOPSIS

 [source]
 ----
-graph [show] [positions]
+graph [options] output.svg
+graph --igraph [show|positions]
 ----

-
-[[description]]
 == DESCRIPTION

-Used to query and manipulate properties of the graph that corresponds to the currently opened .g database. The "show" subcommand displays a list of names and types of the objects from the database along with the positions within the graph of their corresponding nodes and their connection edges. The "positions" subcommand displays for each object in the geometric database its name, type, and node and positions within the graph.
+The *graph* command creates a diagram of the currently open database's
+hierarchy.  Its normal form writes an SVG document to _output.svg_.  The
+output filename must use the `.svg` suffix.

+The `--igraph` form retains the textual graph operations used by older
+GraphEditor/igraph scripts.  It takes exactly one operation: `show` reports
+nodes and connections, and `positions` reports object-node positions.
+
+The command requires the Adaptagrams support library.  Builds without that
+library register the command but report that graph generation is unavailable.
+
+== OPTIONS
+
+*-h*, *--help*::
+Print command usage.
+
+*--tree*::
+Collapse the diagram to a spanning tree, limiting each node to at most one
+incoming graph edge.
+
+*--skip-routing*::
+Write nodes without calculating connector routes.
+
+*--depth* _depth_::
+Limit hierarchy traversal to a non-negative depth.
+
+*--root-obj* _object_::
+Use _object_ as a traversal root.  This option may be repeated to draw several
+rooted subgraphs.
+
+*--igraph*::
+Select the legacy textual mode.  Follow it with `show` or `positions` rather
+than an SVG filename.

-[[examples]]
 == EXAMPLES

-The examples demonstrate the use of the *graph* command and subcommands to access information about the representation of the objects of a database.
-
-.Displays a list with the name and type of the objects along with the nodes' and edges' positions.
+.Write an SVG of the complete hierarchy
 [example]
 ====
-
-mged> **graph show**::
-Displays a list with the name and type of the objects along with the nodes' and edges' positions.
-
-
-
+mged> *graph hierarchy.svg*
 ====

-.Lists the names, types, positions of the corresponding nodes within the graph for the objects in the .g database.
+.Write a depth-limited graph rooted at an assembly
 [example]
 ====
-
-mged> **graph positions**::
-Lists the names, types, positions of the corresponding nodes within the graph for the objects in the currently opened .g database.
-
-
-
+mged> *graph --root-obj all.g --depth 3 assembly.svg*
 ====

+.Use the legacy textual position report
+[example]
+====
+mged> *graph --igraph positions*
+====

-[[author]]
 == AUTHOR

 BRL-CAD Team

-
-[[bug_reports]]
 == BUG REPORTS

-Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org
+Report problems to devs@brlcad.org.
@@ -10,7 +10,7 @@ grid - control the display grid and snap-to-grid behavior

 [source]
 ----
-grid vname parameter [value]
+grid parameter [value ...]
 ----


@@ -19,7 +19,10 @@ grid vname parameter [value]

 The *grid* command controls the view grid: a regular overlay of horizontal and vertical lines drawn on the display to aid in alignment and measurement. It also controls snap-to-grid behavior, which constrains view center movement to the nearest grid intersection.

-The first argument `vname` is the name of the view to configure. The second argument `parameter` specifies which grid attribute to get or set. If a value is provided it sets the attribute; if omitted the current value is returned.
+The `parameter` selects a grid attribute or action for the current view. If a
+value is provided it sets that attribute; if omitted the current value is
+returned. `help` prints the command syntax and `vars` prints every current
+grid value.

 === Parameters

@@ -28,9 +31,13 @@ The first argument `vname` is the name of the view to configure. The second argu
 |Parameter |Value |Description

 |`color`
-|`r g b`
+|`r/g/b`, `r,g,b`, `r;g;b`, or `r g b`
 |Get or set the grid line color as three integers (0–255). With no value, returns current color.

+|`anchor`
+|`x/y/z`, `x,y,z`, `x;y;z`, or `x y z`
+|Get or set the grid anchor in current working units. With no value, returns the current anchor.
+
 |`draw`
 |`0` or `1`
 |Enable (`1`) or disable (`0`) grid display. With no value, returns current draw state.
@@ -59,6 +66,14 @@ The first argument `vname` is the name of the view to configure. The second argu
 |(none)
 |Snap the current view center to the nearest grid intersection. Takes no value argument.

+|`vars`
+|(none)
+|Print all current grid values.
+
+|`help`
+|(none)
+|Print grid command syntax.
+
 |===

 [[examples]]
@@ -67,16 +82,16 @@ The first argument `vname` is the name of the view to configure. The second argu
 .Enable the grid
 [example]
 ====
-mged> **grid default draw 1**
+mged> **grid draw 1**

-Turns on grid display for the view named `default`.
+Turns on grid display for the current view.
 ====

 .Set grid spacing to 10 mm
 [example]
 ====
-mged> **grid default rh 10**
-mged> **grid default rv 10**
+mged> **grid rh 10**
+mged> **grid rv 10**

 Sets horizontal and vertical grid spacing to 10 units in the current working units.
 ====
@@ -84,15 +99,15 @@ Sets horizontal and vertical grid spacing to 10 units in the current working uni
 .Enable snap-to-grid
 [example]
 ====
-mged> **grid default snap 1**
+mged> **grid snap 1**

-Enables snap-to-grid for the `default` view. The view center will snap to the nearest grid point during interactive navigation.
+Enables snap-to-grid for the current view. The view center will snap to the nearest grid point during interactive navigation.
 ====

 .Set grid color to green
 [example]
 ====
-mged> **grid default color 0 200 0**
+mged> **grid color 0;200;0**

 Sets the grid line color to green (R=0, G=200, B=0).
 ====
@@ -100,7 +115,7 @@ Sets the grid line color to green (R=0, G=200, B=0).
 .Get the current horizontal resolution
 [example]
 ====
-mged> **grid default rh**
+mged> **grid rh**

 Returns the current horizontal grid resolution in working units, for example: `10`.
 ====
@@ -108,7 +123,7 @@ Returns the current horizontal grid resolution in working units, for example: `1
 .Snap view center to nearest grid point
 [example]
 ====
-mged> **grid default vsnap**
+mged> **grid vsnap**

 Moves the view center to the nearest grid intersection.
 ====
@@ -26,7 +26,9 @@ The optional `op` argument specifies the Boolean relationship:
 * `-` — subtraction
 * `+` — intersection

-The combination `comb` must already exist. To create a new combination at the same time, use *group*, *comb*, or *region*.
+If the combination `comb` does not already exist, *instance* creates it.  A
+new combination is created as a non-region combination; use *region* when
+region attributes are required.

 [[examples]]
 == EXAMPLES
@@ -10,14 +10,16 @@ knob - Provides a method for simulating knob input. With no options, it will dis

 [source]
 ----
-knob [-e -i -m -v] [[-o] | [v] | [m] | [e] | [k]] [[zap] | [zero] | [id [val]]]
+knob [--help] [--incr] [--view-coords | --model-coords] [--origin v|m|e|k] [action [value] ...]
 ----


 [[description]]
 == DESCRIPTION

-*The *knob* command is used internally by MGED in the processing of knob input devices and is not recommended for users.* The *knob* command provides a method for simulating knob input. With no options, it will display the current values for the knobs. With the *zap or zero* command provided, all the knob values will be reset to zero. If an _id_ and _value_ are provided, the specified knob setting will be simulated. If the _-i_ option is specified, then the value provided will be used as an increment to be applied to the indicated knob. The knobs have different functions depending on the current mode. For example, if in primitive or matrix edit mode and a rotation or translation function is selected, the knob effects are applied to the edited object by default. However, the _-v_ (view coordinates) and _-m_ (model coordinates) options may be used to adjust the view without modifying primitives or matrices. The _-e_ option allows the knob effects to be applied to the edited object when they would normally be applied to the view. The _-o_ option allows the origin of rotation to be specified with _v, m, e,_ and _k_, indicating view, model, eye, and keypoint, respectively. The units for _value_ are degrees for rotation and local units for translation. The available _knob ids_ are:
+*The *knob* command is used internally by MGED in the processing of knob input devices and is not recommended for users.* The *knob* command provides a method for simulating knob input. With no options, it displays the current knob values. It accepts a sequence of actions: *zap*, *zero*, *clear*, *stop*, and *calibrate* take no value; every knob identifier takes one finite numeric value. *zap*, *zero*, *clear*, and *stop* reset the rate-based values. *calibrate* resets the absolute translation baselines.
+
+If the _-i_ / _--incr_ option is specified, each numeric value is applied as an increment. The _-v_ / _--view-coords_ and _-m_ / _--model-coords_ options select the coordinate system and cannot be combined; if neither is given, the current view coordinate setting is used. The _-o_ / _--origin_ option selects the rotation origin: _v_ (view, the default), _m_ (model), _e_ (eye), or _k_ (the current keypoint). Rotation values are in degrees and translation values are in local units. The available knob identifiers are:


 * *x* -- rate-based rotation about horizontal axis.
@@ -34,11 +36,8 @@ knob [-e -i -m -v] [[-o] | [v] | [m] | [e] | [k]] [[zap] | [zero] | [id [val]]]
 * *aY* -- absolute translation in vertical direction.
 * *aZ* -- absolute translation in direction normal to screen.
 * *aS* -- absolute Scale or Zoom.
-* *xadc* -- absolute translation of adc in horizontal direction (screen coordinates -2048 to +2048).
-* *yadc* -- absolute translation of adc in vertical direction (screen coordinates -2048 to +2048).
-* *ang1* -- absolute rotation of adc angle1 (degrees).
-* *ang2* -- absolute rotation of adc angle2 (degrees).
-* *distadc* -- distance setting of the adc (screen coordinates -2048 to +2048).
+
+The command rejects unknown identifiers, missing values, nonnumeric values, and a mixture of view and model coordinate options before modifying the view.


 [[examples]]
@@ -44,17 +44,15 @@ Remove regions from the list in which their parent is a region and the region is
 Specifies descending (z-a) sort order.


-*-0*
-*-1*
-*-2*
-*-3*
-*-4*
-*-5*
-*-6*::
-Specifies sort column 1, 2, 3, 4, 5, or 6 (referring to columns listed in the description of this command); 1 is default. If 0 is specified, the regions are listed in the order in which they are stored, but this will be overridden if *-d*, *-m*, or *-s* options are used, because of the sorting which needs to be done when either of those options is used.
+*-0*, *-1*, *-2*, *-3*, *-4*, *-5*::
+Selects the sort key. *-1* through *-5* sort by region ID, material ID, LOS,
+air code, and region name respectively; *-1* is the default. *-0* keeps the
+stored order. The duplicate-filtering options *-d*, *-m*, and *-s* may still
+sort records as needed to detect matching codes. The displayed region-parent
+column is not a sort-key option.


-*-f FileName*::
+*-f* _FileName_::
 Identifies output should be to a file and specifies the file name. If the path is not included as part of the 'FileName' the path will be the 'current directory'.

 [[examples]]
@@ -42,8 +42,8 @@ Check for full paths that are cyclic - i.e. a situation where a high level objec
 Check for references to objects or files that are missing (not present in the database or on the file system.) Primarily this is a check for comb objects referring to missing objects, but it will also check for and report invalid object and file references in extrude and dsp primitives.


-*-I*, *--invalid-shape* [check [check ...]]::
-Check for shapes in the database that do not satisfy one or more properties required for them to be valid definitions, where correcting the problem requires a change to the object's definition. (As of this writing the only implemented check is for BoT object solidity, but many more are possible and planned.) (Objects invalid due to missing objects are potentially valid without the necessity of changing the object's own definition - e.g. the missing object/file can be added. That category of error can be searched for with the *-M* check.)
+*-I*, *--invalid-shape* [_primitive:technique_ [ ... ]]::
+Check for shapes in the database that do not satisfy one or more properties required for them to be valid definitions, where correcting the problem requires a change to the object's definition. (As of this writing the only implemented check is for BoT object solidity, but many more are possible and planned.) (Objects invalid due to missing objects are potentially valid without the necessity of changing the object's own definition - e.g. the missing object/file can be added. That category of error can be searched for with the *-M* check.) The optional selector is consumed only when it contains a colon, so `lint -I object.g` checks `object.g`, while `lint -I bot:empty object.g` selects the `bot:empty` technique before checking `object.g`. Multiple selectors may be supplied as one quoted argument.


 *-F*, *--filter*::
@@ -10,8 +10,8 @@ list, l - list the attributes and parameters of database objects

 [source]
 ----
-list [-r] [-t] [-v] object(s)
-l [-r] [-t] [-v] object(s)
+list [-r] [-t] [-v ...] object [object ...]
+l [-r] [-t] [-v ...] object [object ...]
 ----


@@ -11,29 +11,42 @@ lod - configure Level of Detail (LOD) drawing
 [source]
 ----
 lod
-lod (on|off|enabled)
-lod scale (points|curves) [factor]
+lod [--help]
+lod [0|1]
+lod csg|mesh [0|1]
+lod cache [clear [all_files]|exists]
+lod scale|point_scale|curve_scale [factor]
+lod bot_threshold [face_count]
+view lod [same arguments]
 ----

 [[description]]
 == DESCRIPTION

-The *lod* command configures the Level of Detail (LoD) drawing behavior for the current view. When LoD drawing is enabled, BRL-CAD adapts the rendering complexity of wireframe geometry based on view conditions, improving performance for complex models.
+The *lod* command configures the Level of Detail (LoD) drawing behavior for the current view. *view lod* is an equivalent spelling. When LoD drawing is enabled, BRL-CAD adapts the rendering complexity of wireframe geometry based on view conditions, improving performance for complex models.

 When called with no arguments, *lod* prints the current LoD configuration, including:

-* Whether adaptive LoD drawing is currently enabled or disabled.
-* The current *point scale* factor.
-* The current *curve scale* factor.
-* The current *BoT face threshold* (the number of faces at which a BoT switches to simplified display).
+* Whether mesh and CSG adaptive LoD drawing are enabled.
+* The current overall, point, and curve scale factors.
+* The current BoT face threshold (the number of faces at which a BoT switches to simplified display).

 === Subcommands

-* *on* : Enable adaptive LoD drawing.
-* *off* : Disable adaptive LoD drawing.
-* *enabled* : Print `1` if LoD is currently enabled, `0` if disabled. Suitable for scripting.
-* *scale points [factor]* : If `factor` is given, sets the point density scale. If omitted, prints the current point scale value.
-* *scale curves [factor]* : If `factor` is given, sets the curve complexity scale. If omitted, prints the current curve scale value.
+* *1* : Enable both mesh and CSG adaptive LoD drawing.
+* *0* : Disable both mesh and CSG adaptive LoD drawing.
+* *csg [0|1]* : Query or set CSG adaptive LoD drawing.
+* *mesh [0|1]* : Query or set mesh adaptive LoD drawing.
+* *scale [factor]* : Query or set the overall LoD scale.
+* *point_scale [factor]* : Query or set the point-density scale.
+* *curve_scale [factor]* : Query or set the curve-complexity scale.
+* *bot_threshold [face_count]* : Query or set the nonnegative BoT face threshold.
+* *cache* : Build the current database's mesh LoD cache.
+* *cache clear* : Clear the in-memory cache.
+* *cache clear all_files* : Clear cache data for all files.
+* *cache exists* : Test whether all BoT and BRep entries have cached LoD data.
+
+All scale values must be finite numbers. The command rejects an unknown action, an invalid binary setting, a negative threshold, or extra action arguments before changing view state.

 [[examples]]
 == EXAMPLES
@@ -44,10 +57,11 @@ When called with no arguments, *lod* prints the current LoD configuration, inclu
 mged> **lod**

 ----
-LoD drawing: enabled
-Point scale: 1.000000
-Curve scale: 1.000000
-BoT face threshold: 32768
+enabled(mesh/csg): 1/1
+scale: 1
+point_scale: 1
+curve_scale: 1
+bot_threshold: 32768
 ----

 Prints the current LoD configuration.
@@ -56,18 +70,18 @@ Prints the current LoD configuration.
 .Enable LoD and reduce curve complexity
 [example]
 ====
-mged> **lod on**
-mged> **lod scale curves 0.5**
+mged> **view lod 1**
+mged> **view lod curve_scale 0.5**

 Enables LoD drawing and halves the curve complexity scale, reducing the number of line segments used to approximate curves.
 ====

-.Check LoD status for scripting
+.Query a single LoD setting
 [example]
 ====
-mged> **lod enabled**
+mged> **lod mesh**

-Returns `1` if LoD is enabled, `0` if disabled. Useful in scripts or Tcl procedures.
+Returns `1` if mesh LoD drawing is enabled and `0` otherwise. Useful in scripts or Tcl procedures.
 ====

 [[author]]
@@ -10,14 +10,15 @@ ls - The command with no _object_ argument lists the name of every object in the

 [source]
 ----
-ls [-A -o -a -c -r -s -p -l -q -H -S] [objects]
+ls [-a -c -r -s -p -l -q -H -S] [objects]
+ls --attributes [--or] [-a -c -r -s -p -l -q -H -S] attribute value [attribute value ...]
 ----


 [[description]]
 == DESCRIPTION

-The command with no _object_ argument lists the name of every object in the database (in alphabetical order) except for those marked as hidden with the *hide* command. If the _object_ argument is supplied, only those _objects_ are listed. The _object_ argument may include regular expressions. If the _-A_ option is used, then the arguments are expected to be a list of attribute name/value pairs, and objects having attributes that match the provided list are listed. By default, an object must match all the specified attributes in order to be listed; however, the _-o_ flag indicates that an object matching at least one attribute name/value pair should be listed. See the *attr* command for information on how to set or get attributes. Regular expressions are not supported for attributes. The following options are also allowed:
+The command with no _object_ argument lists the name of every object in the database (in alphabetical order) except for those marked as hidden with the *hide* command. If the _object_ argument is supplied, only those _objects_ are listed. The _object_ argument may include regular expressions. If the _-A_ option is used, the operands are attribute name/value pairs (one or more complete pairs are required), and objects having attributes that match the provided list are listed. By default, an object must match all the specified attributes in order to be listed; however, the _-o_ flag indicates that an object matching at least one attribute name/value pair should be listed. See the *attr* command for information on how to set or get attributes. Regular expressions are not supported for attributes. The following options are also allowed:


 * `-h`, `--help` -- Print help and exit.
@@ -91,7 +92,7 @@ Lists all combinations with names beginning with "suspension."
 .List all regions having particular attributes.
 [example]
 ====
-mged>**ls -A -o -r Comment{First comment} Comment{Second comment}**
+mged>**ls -A -o -r Comment {First comment} Comment {Second comment}**

 Lists all regions that have a "Comment" attribute that is set to either "First comment" or "Second comment."

@@ -10,18 +10,35 @@ make - Creates a __new_shape__ of the indicated type.

 [source]
 ----
-make [-h] [-t] [-o "x y z"] [-s scale] new_shape type
+make [-o x/y/z] [-s scale] new_shape type
+make -t
+make -h
 ----


 [[description]]
 == DESCRIPTION

-Creates a __new_shape__ of the indicated type. The __new_shape__ is sized according to the current view size and is dependent on the _type_. The possible values for _type_ are:
+Creates a __new_shape__ of the indicated type. The __new_shape__ is sized according to the current view size and is dependent on the _type_.

-The *-h* option prints usage help. The *-o* option specifies the origin for the
-new primitive and the *-s* option sets the initial size scale used when
-building the primitive.
+== OPTIONS
+
+*-o* _x/y/z_::
+Set the primitive origin.  A finite three-component value may be written as
+`x/y/z`, `x,y,z`, `x;y;z`, a quoted `"x y z"` argument, or three separate
+numeric arguments.  The default origin is `0 0 0`.
+
+*-s* _scale_::
+Set the initial size scale.  The default is `1`.
+
+*-t*::
+List the primitive types supported by *make*.  This mode does not accept a
+new-shape name or primitive type.
+
+*-h*, *-H*, *-?*::
+Print usage help.
+
+The possible values for _type_ are:


 * arb8 -- ARB (eight vertices)
@@ -29,7 +29,7 @@ The counter is shared across all calls within the same session and persists unti
 [[options]]
 == OPTIONS

-*-s [num]*::
+*-s* [_num_]::
 Set the internal counter to `num`. If `num` is omitted, the counter is reset to 0.

 [[examples]]
@@ -10,10 +10,9 @@ man - Opens the graphical man page viewer.

 [source]
 ----
-man [cmdname]
-man [-g | --gui] [cmdname]
-man [--no-gui] [-L language] [-S section] [cmdname]
-man [-k|-K] keyword
+man [manual_page [section]]
+man [-g | --gui] [manual_page [section]]
+man [--no-gui] [-L language] [-S section] [manual_page [section]]
 man [-h | --help]
 ----

@@ -25,11 +24,8 @@ Launches the BRL-CAD manual page viewer for the specified command name.

 By default, *man* starts the GUI viewer when possible. It can also force GUI or
 non-GUI mode and can select a manual language or manual section before
-launching `brlman`.
-
-The *-k* and *-K* options search manual pages instead of opening a named page.
-The *-k* option searches names, synopses, and brief descriptions; *-K*
-searches the full manual page text.
+launching `brlman`.  A trailing section argument is accepted for compatibility
+with `man view 3`; the explicit *-S* option is preferred.


 [[options]]
@@ -48,13 +44,7 @@ Force command-line viewer mode.
 Select the manual language to request from `brlman`.

 *-S*, *--section* _section_::
-Select the manual section to request from `brlman`.
-
-*-k* _keyword_::
-Search manual page names, synopses, and brief descriptions.
-
-*-K* _keyword_::
-Search the full manual page text.
+Select manual section `1`, `3`, `5`, or `n` to request from `brlman`.


 [[examples]]
@@ -78,16 +68,6 @@ Launches `brlman` in non-GUI mode and requests section `1` for `rt`.

 ====

-.Search command manual pages.
-[example]
-====
-mged> **man -K "boolean operations"**
-
-Opens the graphical manual page viewer with ranked full-text results.
-
-====
-
-
 [[author]]
 == AUTHOR

@@ -112,14 +112,23 @@ To simply test a density file for validity without attempting to import it, use

 For manipulation of subsets of the data, the *get* and *set* subcommands are provided. *get* will return either one or a set of tuples matching the provided patterns. For density matching a tolerance may be specified to allow for approximate matches. The glob style of pattern matching is supported.

+The *get* filters may be repeated. Numeric *--id* and *--density* filters
+accept exact values and the `<`, `<=`, `>`, and `>=` range forms. Repeated
+filters within one category are alternatives; active id, density, and name
+categories are combined. A positional pattern matches either an id or a
+material name.
+

 [[matermappingdesc]]
 == DENSITY DATABASE MANIPULATION - MAPPING MODE

-The *map* mode of operation uses density information (either from a file or from the current database) to syncronize the *material_id* and *material_name* properties of objects. The *--ids-from-names* mode will use *material_name* properties, perform a lookup on the density database to find a corresponding id number, and update the *material_id*. If an optional mapping file is supplied, the name lookup will also find id assignments based on the name equivalencies specified by the map.
+The *map* mode of operation uses density information (either from a file or from the current database) to synchronize the *material_id* and *material_name* properties of objects. The *--ids-from-names* mode will use *material_name* properties, perform a lookup on the density database to find a corresponding id number, and update the *material_id*. If an optional mapping file is supplied, the name lookup will also find id assignments based on the name equivalencies specified by the map.

 For situations where a file has *material_id* attributes but no names, the *--names-from-ids* option will use density information to assign *material_name* attributes to those objects whose *material_id* values are present. It will also update existing *material_name* values.

+Exactly one of *--ids-from-names* and *--names-from-ids* is required for a
+mapping operation.
+

 [[examples]]
 == EXAMPLES
@@ -10,44 +10,59 @@ material - Used to create, change, retrieve, assign, import, or view materials a

 [source]
 ----
-material assign {object_name_pattern} {material_name}
+material assign {object_name} {material_name}
 ----

-
 [source]
 ----
-material create {object_name_pattern} {material_name}
+material create {object_name} {material_name}
 ----

-
 [source]
 ----
-material import [--id | --name] {file_name}
+material destroy {material_object}
 ----

-
 [source]
 ----
-material get {object_name_pattern} [property_group_name] {property_name}
+material get {material_object} {name | parent | source}
 ----

-
 [source]
 ----
-material remove {object_name_pattern} [property_group_name] {property_name}
+material get {material_object} {physical | mechanical | optical | thermal} {property_name}
 ----

-
 [source]
 ----
-material set {object_name_pattern} [property_group_name] {property_name} {property_value}
+material set {material_object} {name | parent | source} {property_value}
+----
+
+[source]
+----
+material set {material_object} {physical | mechanical | optical | thermal} {property_name} {property_value}
+----
+
+[source]
+----
+material remove {material_object} {name | parent | source}
+----
+
+[source]
+----
+material remove {material_object} {physical | mechanical | optical | thermal} {property_name}
+----
+
+[source]
+----
+material import (--id | --name) {file_name}
 ----


 [[description]]
 == DESCRIPTION

-Used to create, change, retrieve, assign, import, or view materials and their properties. Note that properties and property materials are cases sensitive and should not contain whitespace.
+Used to create, change, retrieve, assign, import, or view materials and their properties. Property, property-group, and material-object names are case-sensitive and should not contain whitespace.

 A newly formed material will have a minimum of the following data set on creation:

@@ -56,9 +71,7 @@ A newly formed material will have a minimum of the following data set on creatio

 * name

-
-
-Material objects are made up of a name (seperate from the object name), parent value, and source value. All of which are variable length strings.
+Material objects have a name (separate from the database object name), parent value, and source value. All three are variable-length strings.

 In addition to the three variable length string properties, material objects also contain four key-value lists used for storing additional material information:

@@ -80,7 +93,7 @@ Set the material_name property of the specified object to the specified material


 *create*::
-Initalize a new material and sets the name property to the value specified.
+Initialize a new material and set its name property to the specified value.


 *destroy*::
@@ -88,19 +101,19 @@ Destroy the material object.


 *get*::
-Retrieve a property of the material, optionally from one of the material's four material groups.
+Retrieve a direct property (name, parent, or source), or a named property from one of the four material property groups.


 *import*::
-Import a density file's entries into material objects. --id denotes the material object names will be the id of the entry in the density table, --name the name of the entry in the density file.
+Import a density file's entries into material objects. Exactly one naming mode is required: --id creates database object names from the density-table IDs (prefixed with `matl`), while --name uses the density-table material names.


 *remove*::
-Remove a material property from the object. (In the case of name, parent, and source this merely sets those values to NULL).
+Remove a material property from the object. For name, parent, and source this clears the direct property.


 *set*::
-Set a material property on the object, optionally from one of the material's four material groups.
+Set a direct property or a property in one of the material's four material groups.



@@ -10,7 +10,7 @@ mirror - Mirrors a shape or combination across a given axis.

 [source]
 ----
-mirror [-p "point"] [-d "dir"] [-x|-y-|-z] [-o offset] {from_object to_object}
+mirror [-p x/y/z] [-d x/y/z] [-x|-y|-z] [-o offset] from_object to_object [axis]
 ----


@@ -22,10 +22,34 @@ If __from_object__ is a shape, then it is copied to a new shape named
 __to_object__ that is mirrored across the given axis. If __from_object__ is a
 combination, then a new combination is created that contains exactly the same
 members named __to_object__. Transformation matrices are added to mirror it
-across the requested axis. The _-x, -y, & -z_ options tell the command which
-axis to mirror the object. The _-p_ can be used to specify a point to mirror
-about, and the _-d_ can be used to specify a direction vector to mirror about.
-The *-h* option prints usage help.
+across the requested axis.
+
+== OPTIONS
+
+*-x*, *-y*, *-z*::
+Select the X, Y, or Z mirror-plane normal.  Options are processed in command
+order, so a later axis option or *-d* value replaces an earlier one.
+
+*-p* _x/y/z_::
+Set a point on the mirror plane.
+
+*-d* _x/y/z_::
+Set a nonzero mirror-plane normal.
+
+For *-p* and *-d*, a finite three-component vector may be written as
+`x/y/z`, `x,y,z`, `x;y;z`, a quoted `"x y z"` argument, or three separate
+numeric arguments.
+
+*-o* _offset_::
+Offset the selected plane normal from the specified point in current units.
+
+_axis_::
+The optional trailing `x`, `y`, or `z` selector is accepted for compatibility
+and overrides an earlier axis choice.  Prefer *-x*, *-y*, or *-z* in new
+commands.
+
+*-h*, *-H*, *-?*::
+Print usage help.


 [[examples]]
@@ -17,7 +17,7 @@ mv from to
 [[description]]
 == DESCRIPTION

-The *move* command (also available as *mv*) renames an existing database object from `from` to `to`. It is a pure rename operation — the object's geometry is unchanged; only its name in the database directory is updated.
+The *move* command (also available as *mv*) renames an existing database object from `from` to `to`. It is a pure rename operation — the object's geometry is unchanged; only its name in the database directory is updated. The destination is a database object name, not a path, and may not contain a slash.

 The command performs the following steps:

@@ -65,13 +65,13 @@ results suitable for programmatic processing.

 == OPTIONS

-*-scope path*::
+*-scope* _path_::
 Restrict the search to regions under the given path. The path may be a
 single object path (for example "/world/room") or a Tcl list of paths.
 If omitted the default scope is the model root "/". Paths that do not
 begin with "/" are normalized by prepending "/".

-*-ray_spacing distance|"auto"*::
+*-ray_spacing* _distance_\|*auto*::
 Spacing between sample rays (in the current local units, or with explicit
 unit suffix). A smaller spacing produces a denser ray sampling and may
 improve accuracy at increased cost. The special value *auto* lets the
@@ -79,12 +79,12 @@ command pick a spacing based on the geometry: it uses the diagonal of
 the combined bounding box of the pair being sampled divided by 100. The
 command reports the spacing values actually used when presenting results.

-*-max_samples n*::
+*-max_samples* _n_::
 Maximum number of sample points along any sampled axis. The command
 computes a sampling grid and clamps the number of samples to this value
 to avoid excessive work. Must be a positive integer. Default is 100.

-*-quiet 0|1*::
+*-quiet* _0_\|_1_::
 When 0 (default), the command prints a human-readable report. When 1 the
 command returns a Tcl list of result records and prints nothing. Use
 quiet mode for scripting and further post-processing.
@@ -528,7 +528,7 @@ Halt push operations at the hierarchy level above regions. See <<npush_region_pu
 Halt push operations at the hierarchy level above solids.


-*-d max_depth*, *--max-depth max_depth*::
+*-d*, *--max-depth* _max_depth_::
 Halt push operations at the hierarchy level specified by __max_depth__. See <<npush_depth_properties,the depth limited push section>> for a description of the properties of depth-limited push that are worth understanding before using this option.


@@ -580,4 +580,3 @@ BRL-CAD Team
 == BUG REPORTS

 Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org
-
@@ -10,14 +10,17 @@ pathlist - Lists all existing paths that start from the specified combinations a

 [source]
 ----
-pathlist {combinations}
+pathlist [-n|--noleaf] combination
 ----


 [[description]]
 == DESCRIPTION

-Lists all existing paths that start from the specified combinations and end at a primitive shape.
+Lists all existing paths that start from the specified combination and end at a
+primitive shape.  The *-n* or *--noleaf* option omits the leaf object from
+each reported path.  The historical *-noleaf* spelling remains accepted for
+compatibility.


 [[examples]]
@@ -28,9 +31,9 @@ The example shows the use of the *pathlist* command to list all paths that start
 .List all paths that start from given combinations and end at a primitive shape.
 [example]
 ====
-mged>**pathlist group1 region2**
+mged>**pathlist group1**

-Lists all existing paths that start from the _combinations group1_ and _region2_ and end at primitive shapes.
+Lists all existing paths that start from _group1_ and end at primitive shapes.

 ====

@@ -22,9 +22,9 @@ The *pix2fb* command reads a raw RGB pixel file (bottom-up row order) and sends

 *Input size*

-* *-w width* : Width of the input pixel file in pixels (default 512).
-* *-n height* : Height of the input pixel file in pixels (default 512).
-* *-s size* : Set both input width and height to `size` (square input).
+* *-w width* : Positive width of the input pixel file in pixels (default 512).
+* *-n height* : Positive height of the input pixel file in pixels (default 512).
+* *-s size* : Set both input width and height to positive `size` (square input).
 * *-a* : Autosize the input — attempt to determine dimensions from the file.

 *Input region (crop)*
@@ -34,9 +34,9 @@ The *pix2fb* command reads a raw RGB pixel file (bottom-up row order) and sends

 *Output (framebuffer) size*

-* *-W scr_width* : Width of the framebuffer display area in pixels.
-* *-N scr_height* : Height of the framebuffer display area in pixels.
-* *-S scr_size* : Set both framebuffer width and height to `scr_size` (square output).
+* *-W scr_width* : Positive width of the framebuffer display area in pixels.
+* *-N scr_height* : Positive height of the framebuffer display area in pixels.
+* *-S scr_size* : Set both framebuffer width and height to positive `scr_size` (square output).

 *Output position*

@@ -50,7 +50,7 @@ The *pix2fb* command reads a raw RGB pixel file (bottom-up row order) and sends
 * *-i* : Inverse (upside-down) — draw the image with inverted row order.
 * *-1* : Force single-line writes (one row at a time).
 * *-m lines* : Streamlined multi-line writes; write `lines` rows per call.
-* *-p seconds* : Pause for `seconds` before closing the framebuffer and exiting.
+* *-p seconds* : Pause for nonnegative `seconds` before closing the framebuffer and exiting.

 [[examples]]
 == EXAMPLES
@@ -10,14 +10,25 @@ plot - Creates a UNIX plot of the current MGED display.

 [source]
 ----
-plot [-float] [-zclip] [-2d] [-grid] [output_file] [filter]
+plot [-2|-3] [-f] [-g] [-z] output_file
+plot [-2|-3] [-f] [-g] [-z] | filter [filter_argument ...]
 ----


 [[description]]
 == DESCRIPTION

-Creates a UNIX plot of the current MGED display. If an __output_file__ is specified, the plot is stored in that file. If a _filter_ is specified, the output is sent to that _filter_. The *-float* option requests a plot file with real numbers rather than integers. The *-zclip* option requests that the plot be clipped to the viewing cube in the Z-direction. The *-2d* option requests a two-dimensional plot (the default is 3D). The *-grid* option is intended to include a grid in the plot, but is currently not implemented. This command does not use the _dm-plot_ display manager. The *pl* command performs the same function, but does use the _dm-plot_ display manager.
+Creates a UNIX plot of the current MGED display. If an __output_file__ is
+specified, the plot is stored in that file. If the first output word is `|`,
+the remaining words form a filter command and the plot is written to its
+standard input. The *-f* option requests a plot file with real numbers rather
+than integers. The *-z* (or *-Z*) option requests that the plot be clipped to
+the viewing cube in the Z-direction. The *-2* option requests a two-dimensional
+plot; *-3* explicitly requests the default three-dimensional plot. The *-g*
+option is accepted but grid output is not implemented. This command does not
+use the _dm-plot_ display manager. The *pl* command performs the same function,
+but does use the _dm-plot_ display manager. The dimension options *-2* and
+*-3* are mutually exclusive.


 [[examples]]
@@ -28,7 +39,7 @@ The example shows the use of the *plot* command to create a UNIX plot of the cur
 .Create a UNIX plot of the current MGED display and send the results to a specified command.
 [example]
 ====
-mged>plot -float | pldebug
+mged>plot -f | pldebug

 Creates a UNIX plot of the current MGED display and pipe the results to the *pldebug* command.

@@ -21,7 +21,8 @@ Writes the current GED display to the specified PNG _file_.

 The implementation supports the following options:

-* *-c r/g/b* - Set the background color using RGB values separated by non-numeric delimiters.
+* *-c r/g/b* - Set the background color.  Accepts packed `r/g/b`, `r,g,b`,
+  or `r;g;b` channels, or three separate 0--255 channel values.
 * *-s size* - Set the output image size in pixels. The implementation requires a size of at least 50.

 Without options, the command writes a 512x512 PNG image with a white background.
@@ -12,7 +12,7 @@ png2fb - load a PNG image into the current display framebuffer
 ----
 png2fb [-H -i -c -v -z -1] [-m lines] [-g screen_gamma]
       [-x file_xoff] [-y file_yoff] [-X scr_xoff] [-Y scr_yoff]
-       [-S squarescrsize] [file.png]
+       [file.png]
 ----


@@ -28,7 +28,7 @@ This command requires the current display manager to have an associated framebuf
 === Options

 *-H*::
-Use the framebuffer's hardware size rather than the PNG image's size for display dimensions.
+Read the PNG header only; do not load image pixels into the framebuffer.

 *-i*::
 Invert the image (flip vertically when reading from file).
@@ -45,27 +45,24 @@ Zoom the image to fill the framebuffer.
 *-1*::
 Use a single line at a time for I/O (slower but uses less memory).

-*-m lines*::
+*-m* _lines_::
 Read `lines` lines at a time from the PNG file (default: vary).

-*-g screen_gamma*::
-Apply the specified gamma correction value to the display.
+*-g* _screen_gamma_::
+Apply the specified positive gamma correction value to the display.

-*-x file_xoff*::
+*-x* _file_xoff_::
 Horizontal offset (in pixels) into the PNG file to start reading.

-*-y file_yoff*::
+*-y* _file_yoff_::
 Vertical offset (in pixels) into the PNG file to start reading.

-*-X scr_xoff*::
+*-X* _scr_xoff_::
 Horizontal offset on the framebuffer screen to begin writing.

-*-Y scr_yoff*::
+*-Y* _scr_yoff_::
 Vertical offset on the framebuffer screen to begin writing.

-*-S squarescrsize*::
-Set both the screen width and height to `squarescrsize` pixels.
-
 [[examples]]
 == EXAMPLES

@@ -10,14 +10,14 @@ pnts - Creates/writes/generates a "pnts" (i.e. point cloud) primitive.

 [source]
 ----
-pnts {subcommand} {subcommand arguments}
+pnts {read|write|gen|tri} {subcommand arguments}
 ----



 [source]
 ----
-read [-f [xyzijksrgb]] [-u unit] [--size #] {input_file} {pnts_obj}
+pnts read [-f [xyzijksrgb]] [-u unit] [--size #] {input_file} {pnts_obj}
 ----


@@ -31,21 +31,21 @@ write [-p #] [-f xyz] [--ply] {pnts_obj} {output_file}

 [source]
 ----
-gen [-t #] [--surface] [--grid] [--rand] [--sobol] [--max-pnts] [--max-time] {obj} {output_pnts}
+pnts gen [-t #] [--surface] [--grid] [--rand] [--sobol] [--max-pnts #] [--max-time #] {obj} {output_pnts}
 ----



 [source]
 ----
-tri [unit] [-s #]
+pnts tri [unit] [-s #] {input_pnts} {output_bot}
 ----



 [source]
 ----
-tri spsr
+pnts tri spsr [options] {input_pnts} {output_bot}
 ----


@@ -60,6 +60,12 @@ Allows the user to create/write/generate "pnts" primitives. See also the
 Most *pnts* subcommands accept *-h* or *--help* to print subcommand-specific
 usage details.

+The *tri* subcommand has three reconstruction methods: *unit*, *ballpivot*,
+and *spsr*.  For compatibility, the method may be omitted when using the
+*unit* method: `pnts tri input_pnts output_bot` is equivalent to
+`pnts tri unit input_pnts output_bot`.  Interactive completion presents the
+explicit method names, while the omitted form remains accepted.
+

 [[subcommands]]
 == SUBCOMMANDS
@@ -69,15 +75,15 @@ usage details.
 Reads point data from an input file.
 +

-*-f [xyzijksrgb]*::
+*-f* [_xyzijksrgb_]::
 Specifies the format of input data


-*-u unit*::
+*-u* _unit_::
 Sepcifies the units - either a named unit (e.g. in), number, or a unit expression (.15mm). Assumes millemeters by default.


-*--size #*::
+*--size* _size_::
 Sets the default size for each point (default is 0).


@@ -105,7 +111,7 @@ Writes output in PLY format.
 Generates a point set from the object and stores the set in a "pnts" primitive.
 +

-*-t #*::
+*-t* _distance_::
 Specifies the sampling grid spacing (in mm)


@@ -125,11 +131,11 @@ Samples using a random Marsaglia ray pattern on the bounding sphere.
 Samples using a Sobol pseudo-random Marsaglia ray pattern on the bounding sphere.


-*--max-pnts*::
+*--max-pnts* _number_::
 Specifies the maximum number of pnts to return per non-grid sampling method.


-*--max-time*::
+*--max-time* _seconds_::
 Specifies the maximum time to spend per method (in seconds) when using non-grid sampling.


@@ -139,7 +145,7 @@ Specifies the maximum time to spend per method (in seconds) when using non-grid
 Generates unit or scaled triangles for each pnt in a point set. If no normal information is present, uses origin at avg of all set points to make normals.
 +

-*-s #*::
+*-s* _scale_::
 Specifies the scale factor to apply to unit triangles - scales the triangle to size with the triangle centered on the original point.


@@ -150,6 +156,13 @@ Apply the Screened Poisson Surface Reconstruction methodology to generate a mesh



+*tri ballpivot*::
+Apply ball-pivoting surface reconstruction to oriented points.  The optional
+*-r*/*--radius* option may be repeated; *--radii* accepts a comma-separated
+radius list.  This method is primarily intended for algorithm experimentation.
+
+
+

 [[examples]]
 == EXAMPLES
@@ -10,7 +10,7 @@ postscript - Temporarily attaches the _Postscript_ display manager and outputs t

 [source]
 ----
-postscript [-f font] [-t title] [-c creator] [-s size_in_inches] [-l line_width] {output_file}
+postscript [-a author] [-b] [-c r/g/b] [-f font] [-s size] [-t title] [-x offset] [-y offset] output_file
 ----


@@ -28,7 +28,9 @@ Set the PostScript creator/author string.
 Draw a border around the output.

 *-c* _r/g/b_::
-Set the border color.
+Set the border color. Each channel is a base-ten integer from 0 through 255.
+The color may be written as _r/g/b_, _r,g,b_, _r;g;b_, or as three separate
+arguments (_r g b_).

 *-f* _font_::
 Set the PostScript font.
@@ -49,7 +51,7 @@ Set the Y offset in inches.
 [[examples]]
 == EXAMPLES

-The first example shows the use of the *postscript* command to place a _PostScript_ version of the current MGED display in a specified file and give it a particular title. The second example is much like the first except that a line width is specified and the title and output file names are different.
+The first example shows the use of the *postscript* command to place a _PostScript_ version of the current MGED display in a specified file and give it a particular title. The second example adds a border and sets its color.

 .Place a _PostScript_ version of the current MGED display in a specified file.
 [example]
@@ -60,12 +62,13 @@ Places a _PostScript_ version of the current MGED display in a file named _test.

 ====

-.Specify the line width of a _PostScript_ version of the current MGED display in a specified file.
+.Specify a border color for a _PostScript_ version of the current MGED display.
 [example]
 ====
-mged>**postscript -l 10 -t "Test Fat Lines" fat_lines.ps**
+mged>**postscript -b -c "40;80;160" -t "Bordered View" bordered.ps**

-Places a _PostScript_ version of the current MGED display with fat lines in a file named __fat_lines.ps__ and titles it Test Fat Lines.
+Places a _PostScript_ version of the current MGED display in __bordered.ps__
+with a blue border.

 ====

@@ -10,7 +10,7 @@ prefix - Changes the name of all the _objects_ listed by adding the specified __

 [source]
 ----
-prefix {new_prefix objects>}
+prefix new_prefix object [object ...]
 ----


@@ -10,14 +10,14 @@ preview - Allows the user to _preview_ animation scripts in MGED.

 [source]
 ----
-preview [-v] [-d delay] [-D start_frame_number] [K end_frame_number] {rt_script_file}
+preview [-e] [-v] [-d delay] [-D start_frame_number] [-K end_frame_number] [-o image_name.ext] rt_script_file
 ----


 [[description]]
 == DESCRIPTION

-Allows the user to _preview_ animation scripts in MGED. The _-d_ option provides a delay in seconds to be applied between each frame (the default is no delay). The _-D_ option allows the user to specify a starting frame number, and the _-K_ option allows the specification of an ending frame number. The _-v_ flag indicates that the objects displayed in the MGED graphics window should be displayed in evaluated mode, as would be the result of the *ev* command. Note that this may significantly slow the _preview_.
+Allows the user to _preview_ animation scripts in MGED. The _-d_ option provides a delay in seconds to be applied between each frame (the default is no delay). The _-D_ option allows the user to specify a starting frame number, and the _-K_ option allows the specification of an ending frame number. The _-v_ flag indicates that the objects displayed in the MGED graphics window should be displayed in evaluated mode, as would be the result of the *ev* command. Note that this may significantly slow the _preview_.  The _-e_ option retains an overlay of the camera eye path.  With _-o image_name.ext_, each displayed frame is written using the supplied base name and extension (or the default PIX form when no extension is supplied).


 [[examples]]
@@ -22,13 +22,13 @@ process list

 [source]
 ----
-process pabort {pid}
+process pabort {pid}...
 ----


 [source]
 ----
-process gabort {glob}
+process gabort {glob}...
 ----


@@ -37,6 +37,9 @@ process gabort {glob}

 The *process* offers a program-agnostic means of managing subprocesses launched by a GED application. The most common instances of this phenomena are long running *rt* commands on large models, but there are other commands such as *rtcheck* that also operate in this asynchronous manner. If one of these processes is running too long or consuming too many resources, *process* allows users to identify and stop these processes from the GED command line.

+The `pabort` subcommand accepts one or more integer process IDs.  The `gabort`
+subcommand accepts one or more command-name glob patterns.
+

 [[examples]]
 == EXAMPLES
@@ -51,14 +54,13 @@ mged>**process**

 ....

-Usage: process [subcommand]
+Usage: process [options] subcommand [args]

 Subcommands:

-  list          - List all currently running subprocesses.
-  pabort <pid>  - Abort the specified subprocess.
-
-  gabort <glob> - Abort all subprocesses whose command matches the glob expression.
+  list         List running GED subprocesses
+  pabort       Abort subprocesses by PID
+  gabort       Abort subprocesses by command glob
      
 ....

@@ -20,6 +20,9 @@ ps [-a author] [-b] [-c r/g/b] [-f font] [-s size] [-t title] [-x offset] [-y of
 The *ps* command shares its core implementation with *postscript*.
 It writes the current display to a PostScript output file.

+The *-c* border color accepts 8-bit RGB channels in _r/g/b_, _r,g,b_, or
+_r;g;b_ form, or as three separate arguments (_r g b_).
+
 See *postscript* for the detailed behavior and option meanings.


@@ -10,14 +10,25 @@ put_comb - Insert combinations and regions - allows definition of both boolean e

 [source]
 ----
-put_comb {comb_name} [is_Region  [[id] | [air] | [material] | [los]]] {color} {shader} {inherit} {boolean_expr}
+put_comb {comb_name} {color} {shader} {inherit} {boolean_expr} {is_region} [region_id air_id material_id los]
 ----


 [[description]]
 == DESCRIPTION

-Command for inserting regions and combinations with attributes set using a single line command - useful in scripting situations.
+Creates or replaces a combination with its attributes set in one command,
+which is particularly useful in scripts.  The first five operands are always
+required: the combination name, color, shader, inheritance flag, and quoted
+Boolean expression.  The next operand selects the kind of combination.  If
+_is_region_ is true, it must be followed by exactly _region_id_, _air_id_,
+_material_id_, and _los_.  If it is false, no trailing region fields are
+allowed.
+
+The color is one command argument.  Integer RGB may be written as
+`r/g/b`, `r,g,b`, `r;g;b`, or, when quoted, `r g b`; each channel is in the
+range 0 through 255.  The ordinary libbu packed color forms, such as
+hexadecimal and normalized floating-point triples, are also accepted.


 [[examples]]
@@ -28,7 +39,7 @@ The *put_comb* expects one of two particular forms of input - combination or reg
 .Specifying a combination using *put_comb*
 [example]
 ====
-mged>**put_comb test.c n 255/255/255 plastic n "u sph.s u arb8.s"**
+mged>**put_comb test.c 255/255/255 plastic n "u sph.s u arb8.s" n**

 Creates a combination that is not a region, using the plastic shader, consisting of the union of sph.s and arb8.s".

@@ -49,7 +60,7 @@ oshader {plastic}
 .Specifying a region using *put_comb*
 [example]
 ====
-mged>**put_comb test.r y 1001 0 32 1 255/255/255 plastic y "u sph.s u arb8.s"**
+mged>**put_comb test.r 255/255/255 plastic y "u sph.s u arb8.s" y 1001 0 32 1**

 Creates a combination that is a region, with region id 1001, air flag off, material 32, los 1, white in color, using the plastic shader, inheriting, consisting of the union of sph.s and arb8.s"

@@ -10,14 +10,19 @@ putmat - Replaces the existing transformation matrix in the combination specifie

 [source]
 ----
-putmat {comb_name/member_name} {[I] | [m0 m1 m2 m3 ... m16]}
+putmat comb_name/member_name [I | m0 m1 m2 m3 ... m15]
 ----


 [[description]]
 == DESCRIPTION

-Replaces the existing transformation matrix in the combination specified that corresponds to the member specified. The transformation matrix may be specified with an I to indicate the identity matrix, or it may be specified as 16 elements listed row-by-row. The *copymat* command allows the user to copy an existing transformation matrix.
+Without a replacement matrix, reports the transformation matrix for the member
+arc.  With a replacement, replaces the existing transformation matrix in the
+specified combination.  The replacement may be *I* for the identity matrix, a
+single quoted string containing 16 finite numbers, or 16 finite numbers listed
+row-by-row. The *copymat* command allows the user to copy an existing
+transformation matrix.


 [[examples]]
@@ -36,19 +36,19 @@ Set or get the type of _effects_ that will occur when firing a query ray. The ef
 Sets or gets the value of _echo_. If set to 1, the actual *nirt* command used will be echoed to the screen.


-*oddcolor* [_r g b_]::
+*oddcolor* [_r/g/b_|_r,g,b_|_r;g;b_|_r g b_]::
 Sets or gets the color of odd partitions.


-*evencolor* [_r g b_]::
+*evencolor* [_r/g/b_|_r,g,b_|_r;g;b_|_r g b_]::
 Sets or gets the color of even partitions.


-*voidcolor* [_r g b_]::
+*voidcolor* [_r/g/b_|_r,g,b_|_r;g;b_|_r g b_]::
 Sets or gets the color of areas where the ray passes through nothing.


-*overlapcolor* [_r g b_]::
+*overlapcolor* [_r/g/b_|_r,g,b_|_r;g;b_|_r g b_]::
 Sets or gets the color of areas that overlap.


@@ -10,7 +10,7 @@ rect - manage the rubber band selection rectangle in the view

 [source]
 ----
-rect vname subcommand [args]
+rect subcommand [args]
 ----

 [[description]]
@@ -18,44 +18,45 @@ rect vname subcommand [args]

 The *rect* command manages a rubber band rectangle overlay drawn on the current view. The rectangle can be positioned, sized, and styled interactively or programmatically. It is primarily used for marquee selection and for raytracing a sub-region of the view.

-The first argument is always the view name (`vname`). The second argument is the subcommand. Each subcommand either gets the current value (no extra args) or sets it (with extra args).
+The first argument is the subcommand for the current view. Each subcommand
+either gets the current value (no extra args) or sets it (with extra args).

 === Subcommands

-*rect vname bg [r g b]*::
-Get or set the rectangle's background fill color as RGB integers (0–255). With no extra args, returns `r g b`. With three args, sets the color.
+*rect bg [r/g/b, r,g,b, r;g;b, or r g b]*::
+Get or set the rectangle's background fill color as RGB integers (0–255). With no extra args, returns `r g b`. One packed or three separate RGB values set the color.

-*rect vname color [r g b]*::
-Get or set the rectangle's border/line color as RGB integers. With no extra args, returns `r g b`. With three args, sets the color.
+*rect color [r/g/b, r,g,b, r;g;b, or r g b]*::
+Get or set the rectangle's border/line color as RGB integers. With no extra args, returns `r g b`. One packed or three separate RGB values set the color.

-*rect vname cdim [w h]*::
+*rect cdim [w h]*::
 Get or set the canvas dimensions (the full window/display size in pixels). Used to compute normalized view coordinates for the rectangle. With no extra args, returns `w h`. With two args, sets the canvas size and recalculates the rectangle's normalized position and dimensions.

-*rect vname dim [w h]*::
+*rect dim [w h]*::
 Get or set the rectangle's dimensions in pixels. With no extra args, returns `w h`. With two args, sets the width and height and recalculates the normalized position.

-*rect vname draw [0|1]*::
+*rect draw [0|1]*::
 Get or set whether the rectangle is drawn. `0` hides, `1` shows. With no extra args, returns the current draw flag.

-*rect vname lstyle [0|1]*::
+*rect lstyle [value]*::
 Get or set the line style. `0` = solid (default), `1` = dashed. With no extra args, returns the current style. Non-zero values set dashed; zero or negative values set solid.

-*rect vname lwidth [w]*::
+*rect lwidth [w]*::
 Get or set the line width in pixels. With no extra args, returns the current width. Non-positive values set the width to 0.

-*rect vname pos [x y]*::
+*rect pos [x y]*::
 Get or set the rectangle's anchor position in pixels (origin at top-left). With no extra args, returns `x y`. With two args, sets the position and recalculates the normalized coordinates.

-*rect vname rt port*::
+*rect rt port*::
 Raytrace the geometry within the current rectangle area, sending output to the framebuffer at the given `port` number. Requires exactly one argument. Has no effect if the rectangle has zero size.

-*rect vname zoom*::
+*rect zoom*::
 Zoom the view to fill the screen with the area enclosed by the rectangle. Adjusts the rectangle to match the window aspect ratio before zooming. Has no effect if the rectangle has zero size.

-*rect vname vars*::
+*rect vars*::
 Print all current rectangle parameters as `variable = value` pairs. Useful for inspecting the complete rectangle state.

-*rect vname help*::
+*rect help*::
 Print the usage summary for all subcommands.

 [[examples]]
@@ -64,17 +65,17 @@ Print the usage summary for all subcommands.
 .Show the rectangle
 [example]
 ====
-mged> **rect default draw 1**
+mged> **rect draw 1**

-Enables display of the rubber band rectangle on the `default` view.
+Enables display of the rubber band rectangle on the current view.
 ====

 .Position and size the rectangle
 [example]
 ====
-mged> **rect default cdim 1024 768**
-mged> **rect default pos 200 100**
-mged> **rect default dim 400 300**
+mged> **rect cdim 1024 768**
+mged> **rect pos 200 100**
+mged> **rect dim 400 300**

 Sets the canvas to 1024×768 pixels, anchors the rectangle at pixel (200, 100), and gives it a 400×300 pixel size. The normalized view coordinates are calculated automatically.
 ====
@@ -82,7 +83,7 @@ Sets the canvas to 1024×768 pixels, anchors the rectangle at pixel (200, 100),
 .Set the rectangle color to red
 [example]
 ====
-mged> **rect default color 255 0 0**
+mged> **rect color 255;0;0**

 Sets the border color of the rectangle to red.
 ====
@@ -90,7 +91,7 @@ Sets the border color of the rectangle to red.
 .Use dashed lines
 [example]
 ====
-mged> **rect default lstyle 1**
+mged> **rect lstyle 1**

 Switches the rectangle border to a dashed line style.
 ====
@@ -98,7 +99,7 @@ Switches the rectangle border to a dashed line style.
 .Zoom to the rectangle area
 [example]
 ====
-mged> **rect default zoom**
+mged> **rect zoom**

 Adjusts the view so that the area within the rectangle fills the display.
 ====
@@ -106,7 +107,7 @@ Adjusts the view so that the area within the rectangle fills the display.
 .Inspect all rectangle parameters
 [example]
 ====
-mged> **rect default vars**
+mged> **rect vars**

 Prints all current rectangle settings, e.g. position, dimensions, colors, draw flag, line style, and line width.
 ====
@@ -10,14 +10,24 @@ red - Creates a file describing the specified combination and starts an editor f

 [source]
 ----
-red {combination}
+red [-f] [-E editor] combination
 ----


 [[description]]
 == DESCRIPTION

-Creates a file describing the specified combination and starts an editor for the user to modify the combination. The environment _EDITOR_ variable will be used to select the editor. If _EDITOR_ is not set, then _/bin/ed_ will be used. All the attributes of BRL-CAD regions and _combinations_ may be edited in this way. The region-specific attributes will be ignored if the _combination_ is not a region and is not set to be a _region_ during editing. It is not necessary to be in an editing mode to run this command. The *rm, r, comb, c,* and *g* commands provide some basic combination editing capabilities.
+Creates a file describing the specified combination and starts an editor for
+the user to modify the combination. The environment _EDITOR_ variable selects
+the editor, or _/bin/ed_ is used when it is unset. `-E editor` overrides that
+selection for this invocation. `-f` permits replacing an existing combination
+if the edited text renames it to an already occupied name.
+
+All the attributes of BRL-CAD regions and _combinations_ may be edited in this
+way. The region-specific attributes will be ignored if the _combination_ is
+not a region and is not set to be a _region_ during editing. It is not
+necessary to be in an editing mode to run this command. The *rm, r, comb, c,*
+and *g* commands provide some basic combination editing capabilities.


 [[examples]]
@@ -24,7 +24,7 @@ The 'reid' command sequentially assigns the 'region_id' attribute value for all
 == OPTIONS


-*-n num*::
+*-n* _num_::
 Increment to use between consecutive region identifiers. The default is 1.


--- a/Show More
+++ b/Show More