Classes
class	ScaffoldResult

Functions
str	_architecture_md (str name)
str	_run_tests_py (str name)
str	_tests_readme (str name)
str	_docs_readme (str name)
str	_octrc_json ()
ScaffoldResult	run_scaffold (str name, Path base_dir, *, bool dry_run=False, bool include_venv=True)
None	_write_doxyfile (Path project_dir, str name, ScaffoldResult result)
None	_copy_sphinx_templates (Path project_dir, str name, ScaffoldResult result)
None	_write_fresh_oc_status (Path project_dir, ScaffoldResult result)
None	_create_venv (Path project_dir, ScaffoldResult result)
None	_copy_claude_skills (Path project_dir, ScaffoldResult result, *, bool dry_run=False)

Variables
Path	_SPHINX_TEMPLATES_DIR = Path(__file__).resolve().parents[1] / "templates" / "sphinx"
dict	_DEBUG_CONFIG_TEMPLATE
tuple	_GITIGNORE_LINES
tuple	_OCTIGNORE_LINES
tuple	_CLAUDE_SKILLS_TEMPLATE_DIR

Detailed Description

Purpose
-------
OI-512 / FS-518 - project scaffolding. Lifts the scaffold body out of
``oct/cli.py`` so the CLI becomes a thin dispatcher and so the venv
integration (FS-503 / FS-504) can layer on a single ``include_venv``
parameter rather than a second 135-line rewrite.

The public entry point is :func:`run_scaffold`, which returns a
:class:`ScaffoldResult` describing what was created, skipped, or warned
about. Callers are expected to render the result themselves - this
module never touches ``click.echo`` directly.

Responsibilities
----------------
- Materialise the standard Option C directory layout under a target path.
- Write bundled templates: ``.octrc.json``, Sphinx ``conf.py`` /
  ``index.rst``, the debug-config skeleton, stub READMEs.
- Optionally create a ``.venv/`` via :mod:`venv` (``include_venv``).
- Run in dry-run mode where no filesystem state changes.

Diagnostics
-----------
Domain: SCAFFOLD
Levels:
    L2 - lifecycle: start / end / target path
    L3 - semantic details: per-template decisions
    L4 - deep tracing: per-file / per-dir outcomes

Contracts
---------
- ``run_scaffold`` must be side-effect-free when ``dry_run=True``.
- Venv creation must never shell out - uses :class:`venv.EnvBuilder`.
- The Sphinx template directory is resolved at import time to keep
  ``run_scaffold`` self-contained.

Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
- oct.core.option_c_dir (OcStatus, write_oc_status)
- oct.docs.doxyfile_init (lazy; stamps the Doxyfile from the bundled template)

Function Documentation

◆ _architecture_md()

str oct.scaffold.oct_scaffold._architecture_md ( str name )

protected

Seed ``docs/ARCHITECTURE.md`` with the workspace's overview-chart slot.

Every subproject's architecture document carries a section headed
exactly ``Architecture overview``: one Mermaid flowchart of intent,
then how to read it and what it leaves out (plan B of
``docs/DOCS_OVERVIEW_CHARTS_PLAN_2026-09-27.md``). Seeding the slot is
what makes a new project arrive with the convention rather than
acquire it later. The placeholder chart is valid Mermaid, so the
first Sphinx build renders it instead of failing on it.

Definition at line 137 of file oct_scaffold.py.

Here is the caller graph for this function:

◆ _copy_claude_skills()

None oct.scaffold.oct_scaffold._copy_claude_skills	(	Path	project_dir,
		ScaffoldResult	result,
		*	,
		bool	dry_run = False )

protected

FS-541: copy the bundled Claude Code skills into the project.

Definition at line 595 of file oct_scaffold.py.

◆ _copy_sphinx_templates()

None oct.scaffold.oct_scaffold._copy_sphinx_templates	(	Path	project_dir,
		str	name,
		ScaffoldResult	result )

protected

Render and copy the bundled Sphinx template pack into ``docs/``.

Silently skips (with a ``messages`` note) when the bundled template
directory is missing - typical for source checkouts that omit the
templates pack.

Definition at line 458 of file oct_scaffold.py.

Here is the caller graph for this function:

◆ _create_venv()

None oct.scaffold.oct_scaffold._create_venv	(	Path	project_dir,
		ScaffoldResult	result )

protected

Create a ``.venv/`` at the project root using :mod:`venv`.

Any OS-level failure is downgraded to a ``messages`` warning so the
caller can continue - a failed venv should not abort scaffolding.

Definition at line 564 of file oct_scaffold.py.

Here is the caller graph for this function:

◆ _docs_readme()

str oct.scaffold.oct_scaffold._docs_readme ( str name )

protected

Definition at line 187 of file oct_scaffold.py.

Here is the caller graph for this function:

◆ _octrc_json()

str oct.scaffold.oct_scaffold._octrc_json ( )

protected

OI-530: build the scaffolded ``.octrc.json``.

Ships with a live ``linter.profile`` default plus an underscore-prefixed
``_git_example`` stanza. JSON has no comments, so we use the same
``_<name>`` convention that ``_schema_version`` and other sentinels
already use elsewhere: :func:`oct.core.octrc.load_octrc_safe` ignores
underscore-prefixed top-level keys, so the example is discoverable but
inert until the operator renames it.

Definition at line 197 of file oct_scaffold.py.

Here is the caller graph for this function:

◆ _run_tests_py()

str oct.scaffold.oct_scaffold._run_tests_py ( str name )

protected

Definition at line 168 of file oct_scaffold.py.

Here is the caller graph for this function:

◆ _tests_readme()

str oct.scaffold.oct_scaffold._tests_readme ( str name )

protected

Definition at line 178 of file oct_scaffold.py.

Here is the caller graph for this function:

◆ _write_doxyfile()

None oct.scaffold.oct_scaffold._write_doxyfile	(	Path	project_dir,
		str	name,
		ScaffoldResult	result )

protected

Stamp ``docs/doxygen_work_dir/Doxyfile`` via :mod:`oct.docs.doxyfile_init`.

A missing bundled template is reported in ``messages`` rather than
raised, matching how the Sphinx pack is handled: the scaffold as a
whole must still succeed on a checkout that omits templates.

Definition at line 437 of file oct_scaffold.py.

Here is the caller graph for this function:

◆ _write_fresh_oc_status()

None oct.scaffold.oct_scaffold._write_fresh_oc_status	(	Path	project_dir,
		ScaffoldResult	result )

protected

FS-539: emit ``oc_status.json`` for a newly-scaffolded project.

A fresh scaffold is ``stage="compliant"`` with every pillar enabled -
the scaffolder writes the full Option C layout, so every pillar is
satisfied on day zero. ``migrated_from`` is an empty dict because the
project was born in the ``.option_c/`` layout rather than migrated.

Definition at line 525 of file oct_scaffold.py.

Here is the caller graph for this function:

◆ run_scaffold()

ScaffoldResult oct.scaffold.oct_scaffold.run_scaffold	(	str	name,
		Path	base_dir,
		*	,
		bool	dry_run = False,
		bool	include_venv = True )

Create a new Option C project under ``base_dir / name``.

Parameters
----------
name
    Project name (becomes the top-level directory).
base_dir
    Parent directory - the project is created at ``base_dir / name``.
dry_run
    When True, describe what would happen without touching the
    filesystem.
include_venv
    When True, create a ``.venv/`` at the project root using the
    stdlib :mod:`venv` module.

Returns
-------
ScaffoldResult
    Structured result. Always returns; never raises for existing
    files (they are recorded in ``skipped``).

Definition at line 303 of file oct_scaffold.py.

Here is the call graph for this function:

Variable Documentation

◆ _CLAUDE_SKILLS_TEMPLATE_DIR

tuple oct.scaffold.oct_scaffold._CLAUDE_SKILLS_TEMPLATE_DIR

protected

Initial value:

=  (
    Path(__file__).resolve().parents[1] / "templates" / "claude_skills"
)

Definition at line 590 of file oct_scaffold.py.

◆ _DEBUG_CONFIG_TEMPLATE

dict oct.scaffold.oct_scaffold._DEBUG_CONFIG_TEMPLATE

protected

Initial value:

=  {
    "_schema_version": "2.0",
    "DEBUG_LEVELS": {
        "GENERAL": {"level": 2, "color": "default"}
    },
    "global_settings": {
        "silent_mode": False,
        "enable_timestamps": True,
        "enable_colors": True,
        "include_filename": True,
        "output_mode": "both",
        "log_to_file": True,
        "log_file_path": None,
        "log_format": "text",
        "log_rotation": {
            "max_files": 10,
            "max_size_mb": 5.0,
        },
        "global_debug_level": None,
        "watch_config": False,
        "ai_trace_level": False,
        "redaction_patterns": [],
        "mode": "dev",
    },
    "instrumentation_enabled": False,
    "http_redact_headers": ["authorization", "cookie", "set-cookie", "x-api-key"],
}

Definition at line 74 of file oct_scaffold.py.

◆ _GITIGNORE_LINES

tuple oct.scaffold.oct_scaffold._GITIGNORE_LINES

protected

Definition at line 234 of file oct_scaffold.py.

◆ _OCTIGNORE_LINES

tuple oct.scaffold.oct_scaffold._OCTIGNORE_LINES

protected

Initial value:

=  (
    "# oct-specific ignores - lint/format/test/deps all consult this file.",
    ".venv/",
    "venv/",
    "env/",
    "docs/_build/",
    "docs/html/",
    "docs/doxygen_output/",
    "build/",
    "dist/",
    ".formatter_archive/",
)

Definition at line 284 of file oct_scaffold.py.

◆ _SPHINX_TEMPLATES_DIR

Path oct.scaffold.oct_scaffold._SPHINX_TEMPLATES_DIR = Path(__file__).resolve().parents[1] / "templates" / "sphinx"

protected

Definition at line 67 of file oct_scaffold.py.

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ _architecture_md()

◆ _copy_claude_skills()

◆ _copy_sphinx_templates()

◆ _create_venv()

◆ _docs_readme()

◆ _octrc_json()

◆ _run_tests_py()

◆ _tests_readme()

◆ _write_doxyfile()

◆ _write_fresh_oc_status()

◆ run_scaffold()

Variable Documentation

◆ _CLAUDE_SKILLS_TEMPLATE_DIR

◆ _DEBUG_CONFIG_TEMPLATE

◆ _GITIGNORE_LINES

◆ _OCTIGNORE_LINES

◆ _SPHINX_TEMPLATES_DIR