Add --format md|html|xml to socrates pack

README.md

@@ -178,6 +178,30 @@ Auto-detection: if the project sits inside a CompanyOS layout (`builds/<project>
 
 Pattern files are named `CANDIDATE-<slug>.md`. Promote a candidate to a real pattern by dropping the `CANDIDATE-` prefix **only after** it has worked on at least one additional project.
 
+### `socrates pack [path]` — assemble an Architect input bundle
+
+Concatenates every load-bearing planning file (AGENTS, README, STATE, DOMAIN, DECISIONS, RISKS, QUESTIONS) plus the active sprint's four files into one paste-able bundle for the Architect (Claude Chat / ChatGPT / etc.). Output goes to `.socrates-architect-pack.<ext>` in the project root, or to stdout with `--stdout`.
+
+```bash
+socrates pack                          # write .socrates-architect-pack.md
+socrates pack --stdout                 # print to stdout
+socrates pack --sprint 002-rebate-engine   # override the auto-detected sprint
+socrates pack --include-philosophy     # prepend socrates' own 120x stance summary
+socrates pack --kit-path ~/120x-kit    # also embed the kit's three load-bearing files
+socrates pack --format xml             # XML section delimiters around markdown bodies
+socrates pack --format html            # full HTML (requires the [html] extra)
+```
+
+| Flag | Effect |
+|---|---|
+| `--sprint <name>` | include this sprint folder instead of auto-detecting the highest-numbered one |
+| `--stdout` | print to stdout instead of writing the file |
+| `--include-philosophy` | prepend a short, original 120x stance written by socrates |
+| `--kit-path PATH` | also embed the kit's three load-bearing files (or use `$SOCRATES_KIT_PATH`) |
+| `--format md\|html\|xml` | output format. `md` (default), `xml` (markdown wrapped in `<section>` tags — matches Anthropic's prompt-engineering recommendation), `html` (full HTML, requires `pip install socrates120x[html]`) |
+
+The output file extension follows the format: `.md`, `.xml`, or `.html`. The default `md` keeps the historical behavior. `xml` adds ~5% token overhead but gives the Architect explicit structural delimiters. `html` adds ~30-50% token overhead and requires the optional `markdown` dependency — use it when you're explicitly testing whether full HTML helps the Architect on your specific content.
+
 ### `socrates companyos <path>` — scaffold the macro layer
 
 Creates the CompanyOS skeleton: `clients/`, `builds/`, `pipeline/`, `patterns/`, `content/`, `reference/`, `daily/`, `templates/`, plus an `AGENTS.md` router that points each subfolder at its role.

pyproject.toml

@@ -23,6 +23,13 @@ dev = [
     "pytest>=8.0",
     "ruff>=0.4",
     "mypy>=1.9",
+    "markdown>=3.5",  # exercised by --format html tests
+]
+html = [
+    # Required by `socrates pack --format html`. Optional because the
+    # default markdown pack format is pure-stdlib; users who never run
+    # the HTML format shouldn't have to install anything extra.
+    "markdown>=3.5",
 ]
 
 [project.scripts]

src/socrates120x/cli.py

@@ -140,6 +140,17 @@ def main(argv: list[str] | None = None) -> int:
             "embedded in the pack. Falls back to the $SOCRATES_KIT_PATH env var."
         ),
     )
+    pack.add_argument(
+        "--format", choices=("md", "html", "xml"), default="md",
+        dest="pack_format",
+        help=(
+            "Output format. `md` (default) is plain markdown — the historical "
+            "behavior. `xml` wraps markdown bodies in <section> tags, matching "
+            "Anthropic's prompt-engineering recommendation for structural "
+            "delimitation. `html` produces full HTML (requires the optional "
+            "`markdown` package: `pip install socrates120x[html]`)."
+        ),
+    )
 
     patterns = sub.add_parser(
         "patterns",
@@ -489,11 +500,17 @@ def _cmd_pack(args: argparse.Namespace) -> int:
         "include_sprint": args.sprint,
         "include_philosophy": args.include_philosophy,
         "kit_path": args.kit_path,
+        "format": args.pack_format,
     }
-    if args.stdout:
-        print(build_pack(project, **kwargs))
-        return 0
-    target = write_pack(project, **kwargs)
+    try:
+        if args.stdout:
+            print(build_pack(project, **kwargs))
+            return 0
+        target = write_pack(project, **kwargs)
+    except RuntimeError as exc:
+        # Raised by --format html when the `markdown` package is missing.
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
     print(f"Wrote {target}")
     return 0