Summary
Add a repo-local onboarding guide for auto-term-catalog that complements the broader CultureBotAI onboarding materials.
This guide should do two things clearly:
- explain why the Codex CLI is the most useful entry point for working in this repo
- explain why good repo setup matters for our future selves and our collaborators, not just for getting one script to run once
Why this matters
Marcin's ecosystem already has broader onboarding material, but this repo still has repo-specific gaps that create unnecessary friction for new contributors.
Current repo gaps include:
- no
pyproject.toml
- no pinned Python version
- no lockfile
- no CI
- no tests
- hard-coded local input path in
src/process_terms/auto_terms_table.py
That means a new undergraduate can be onboarded into the broader CultureBotAI world and still not have enough repo-specific guidance to work productively and reproducibly here.
Framing to emphasize in the doc
Why Codex CLI here
The guide should emphasize that the CLI is especially useful for this repo because it:
- runs directly in the checked-out repository
- works naturally with shell commands, Git, local files, and generated artifacts
- keeps contributors close to the real execution environment
- makes the connection between prompts, commands, files, and version control explicit
It should explicitly position the CLI relative to other entry points:
- web interface: useful, but less grounded in the local repo state
- desktop app: convenient, but still one step removed from the shell workflow
- IDE plugin: helpful later, but not a substitute for understanding how the repo actually runs
Why repo setup matters
The guide should also emphasize that good repo setup is for:
- our future selves
- the next student
- collaborators reviewing or extending the work
- anyone trying to reproduce results later
Undergraduates often optimize for getting something to run once. This guide should push the repo toward repeatable, inspectable, shareable workflows instead.
Scope
The repo-local guide should:
- start with Homebrew installation
- cover Node/npm and Codex CLI installation
- explain the
Sign in with ChatGPT flow for LBL-provisioned access
- clarify that
@lbl.gov alone is not sufficient without actual workspace provisioning
- document the current repo gaps
- recommend a practical Python version and repo infrastructure baseline
Positioning
This should be presented as:
- repo-local
- complementary to broader CultureBotAI onboarding
- aligned with cross-repo best-practices efforts
Follow-on work
A later issue/PR should implement the actual repo bootstrap:
- add
pyproject.toml
- pin Python version
- add tests
- add CI
- replace hard-coded paths with CLI arguments
Summary
Add a repo-local onboarding guide for
auto-term-catalogthat complements the broader CultureBotAI onboarding materials.This guide should do two things clearly:
Why this matters
Marcin's ecosystem already has broader onboarding material, but this repo still has repo-specific gaps that create unnecessary friction for new contributors.
Current repo gaps include:
pyproject.tomlsrc/process_terms/auto_terms_table.pyThat means a new undergraduate can be onboarded into the broader CultureBotAI world and still not have enough repo-specific guidance to work productively and reproducibly here.
Framing to emphasize in the doc
Why Codex CLI here
The guide should emphasize that the CLI is especially useful for this repo because it:
It should explicitly position the CLI relative to other entry points:
Why repo setup matters
The guide should also emphasize that good repo setup is for:
Undergraduates often optimize for getting something to run once. This guide should push the repo toward repeatable, inspectable, shareable workflows instead.
Scope
The repo-local guide should:
Sign in with ChatGPTflow for LBL-provisioned access@lbl.govalone is not sufficient without actual workspace provisioningPositioning
This should be presented as:
Follow-on work
A later issue/PR should implement the actual repo bootstrap:
pyproject.toml