Skip to content

Add repo-local onboarding guide emphasizing Codex CLI workflow and reproducible repo setup #7

@turbomam

Description

@turbomam

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions