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	_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)

Function Documentation

◆ _architecture_md()

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

protected

Definition at line 136 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 532 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 395 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 501 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 164 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 174 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 145 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 155 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 462 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 266 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 527 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 73 of file oct_scaffold.py.

◆ _GITIGNORE_LINES

tuple oct.scaffold.oct_scaffold._GITIGNORE_LINES

protected

Definition at line 209 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/",
    "build/",
    "dist/",
    ".formatter_archive/",
)

Definition at line 249 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 66 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_fresh_oc_status()

◆ run_scaffold()

Variable Documentation

◆ _CLAUDE_SKILLS_TEMPLATE_DIR

◆ _DEBUG_CONFIG_TEMPLATE

◆ _GITIGNORE_LINES

◆ _OCTIGNORE_LINES

◆ _SPHINX_TEMPLATES_DIR