docs(questions): add Answers/Explainers 2025-17-09-14:46 summarizing decisions and approach

collab/questions/00-bootstrap.md

@@ -168,8 +168,13 @@ No
 
 ### CLI UX and workflow
 1. Subcommands vs flags-only: prefer simple flags (e.g., `CodexHelper --mode SAASApp --new-project`) or explicit subcommands (`CodexHelper new-project --mode SAASApp`)? Please pick one.
+
+What are the tradeoffs? I don't really have a strong opinion either way. What do you think is the better UX? I think the subcommands looks a bit nicer.
+
 2. Project creation flow: confirm that `CodexHelper` runs from any project dir outside this repo to scaffold project files for a chosen mode; this repo is only for modes and the wrapper. Correct?
 
+That iscorrect. Modes, wrapper, prompts to be explicit.  (Of course a mode would have prompts and (eventaully) MCP config templates etc). I think we are on the same page.  Now, CodexHelper would run inside the repo to create a new mode. That would be the only command supported when running inside the repo (it would scaffold a new mode for bootstrap via filling out markdown intake files). 99.9% of the CodexHelper usage will be outside of the repo, yes.
+
 ### Templates and scaffolding
 3. Examples for project scaffolding (pick what you want generated initially):
    - prompts/: `project.md` (narrative), optional `style.md`
@@ -178,18 +183,65 @@ No
    - runs/: created on first run, ignored by VCS
    Keep/delete/adjust which of these?
 
+All of that looks good. What about the system prompt/mode prompt? And I presume the codex.sh invoking of codex would also automatically pass in project.md (and somehow the system/mode prompt as well)? Can the system/mode prompt be copied (read only) to the project directory? THis would allow the entire thing to be self contained/commited to git etc? And the read only bit could easily be removed if the user wants to edit the system/mode prompt.
+   
+
 ### Prompts composition
 4. Confirm stacking order: Global system rules → Mode rules → Project narrative prompt. OK?
+
+Yes. That is correct.
+
 5. Locations proposal: `prompts/global/system.md` (repo-wide), `modes/<name>/system.md` (optional overlay), `modes/<name>/mode.md` (mode rules), project `prompts/project.md`. Approve?
 
+What would the optional overlay be for? Tell me more about that?
+project.md wouldn't be in this repo (or is that a blank placeholder file (or maybe a one line "put your instructions here" or something)) that gets copied into the project directory during bootstrap?
+
 ### Config and tooling
 6. Format/tooling: choose YAML + `yq` as the single supported format/tool. Approve?
+Yes
+
+## Answers/Explainers 2025-17-09-14:46
+
+- Name & install:
+  - Use `CodexHelper` as the entrypoint script. No system install; user adds repo script to PATH. Provide optional `bin/install.sh` to symlink into `~/bin`.
+- Binary discovery:
+  - Resolve with `which codex` then `which codex-cli`; allow `CODEX_BIN` to override. If missing, print guidance; no auto-install.
+- CLI UX:
+  - Subcommands provide clearer UX and self-documentation; we recommend: `CodexHelper new-project`, `CodexHelper new-mode`, `CodexHelper run`. We can later add flag-only aliases if desired.
+- Where to run:
+  - Outside this repo: support `new-project` and `run` for user projects. Inside this repo: only `new-mode` (to scaffold a mode via markdown intake).
+- Project scaffolding contents:
+  - Generate in project: `prompts/project.md` (narrative), optional `prompts/style.md` (coding/style notes), `codex.yaml` (mode/config/MCP placeholders), `codex.sh` (entrypoint wrapper). Create `runs/` on first run and add to `.gitignore`.
+  - Copy mode/system prompts into project under `prompts/_mode/` as read-only copies (cannot enforce, but mark with header comment). `codex.sh` will compose prompts in order.
+- Prompt composition:
+  - Stack: Global system rules → Mode rules → Project narrative. The optional mode-specific system overlay is an extra system-level rules file for a mode when it needs to extend or tweak the global system rules.
+  - Locations: `prompts/global/system.md` (repo-wide), `modes/<name>/system.md` (optional overlay), `modes/<name>/mode.md` (mode rules), project `prompts/project.md`.
+- Config/tooling:
+  - Use YAML with `yq`. Precedence: CLI > env > project > mode > global defaults. Pass through sandbox/full-auto flags to codex.
+- Safety & outputs:
+  - Never overwrite without `--force`. Never run `git push` for user projects. Write runs to `<project>/runs/<timestamp>/...`. Prevent `run` inside this repo except for `new-mode`.
+- Licensing:
+  - Repo (wrapper, modes, prompts) under AGPLv3. User project artifacts (prompts/code generated) are user-licensed; we will not inject a LICENSE into projects.
+- OS target:
+  - Ubuntu 22.04/Debian 12+ with bash/zsh. Dependencies: bash, git, yq.
+
 7. Precedence final confirm: CLI > env > project > mode > global defaults. Approve?
+
+Yes
+
 8. Binary detection: detect `codex` then `codex-cli`, override with `CODEX_BIN`. On missing, print instructions; no auto-install. Approve?
 
+Yes
+
 ### Outputs and safety
 9. Runs location: always `<cwd>/runs/<timestamp>/...` (never in this repo unless creating modes). Approve?
+Yes
+
 10. Safety: never overwrite without `--force`; never run `git push` in user projects. Anything else to lock down?
 
+Cant think of anything
+
 ### Install convenience
 11. Provide optional `bin/install.sh` to symlink `CodexHelper` into `~/bin` (no sudo). Include or skip?
+
+Yes