onboard
- Repo stars 0
- Author repo skills-registry
- Domain
- Security
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @tomevault-io · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- Python >=3.11
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# User Onboarding
Use the shared repo-local onboarding flow:
1. `tools/onboard.ps1` or `tools/onboard.sh` for the pre-Python cold-start step
2. `tools/onboard_driver.py` for agent orchestration once Python exists
3. `tools/bootstrap.py` as the shared Python-level audit/plan/apply engine
Do not duplicate bootstrap logic here when the repo scripts already handle it.
## Hard Rules
- Print `Scanning your environment...` before discovery.
- Print `Testing WRDS connectivity...` before live `psql` checks.
- Never assume bare `python` or bare `pip` are valid on Windows.
- Prefer `uv pip install --python "<PYTHON>"` when uv is available; fall back to `"<PYTHON>" -m pip install`.
- Prefer `tools/bootstrap.py audit`, the emitted `bootstrap_plan`, and `tools/bootstrap.py apply` over ad hoc local-file generation.
- Treat canonical local state as external to the repo. Repo-root `LOCAL_ENV.md`, `CLAUDE.local.md`, and `.claude/settings.local.json` are compatibility shims only.
- Let `tools/bootstrap.py apply` manage canonical local state. Use `--write-compat-shims` only for private single-user backward compatibility.
- If an install path needs admin privileges or a missing package manager, stop and give exact instructions.
- If a bootstrap-plan command needs approval, request it and continue with that exact command.
- Ask once whether the user has a WRDS account and wants it configured now. If the answer is no, skip WRDS setup and still treat onboarding as complete once the base repo is ready.
- Treat SSH key setup as optional for basic PostgreSQL access.
- Never use `conda install` for system tools (psql, pdflatex, R, git). Use the OS package manager (winget/brew/apt). Conda is for Python packages only.
## Workflow
### 1. Start With The Shell Entry Point
Use the repo-local shell entrypoint, not `tools/bootstrap.py` directly, when the
machine may not have Python yet.
```powershell
powershell -ExecutionPolicy Bypass -File tools/onboard.ps1
```
```bash
bash tools/onboard.sh
```
Those entrypoints should:
- find a usable Python 3.11+ interpreter
- install Miniforge automatically when no acceptable Python exists and a
supported installer path is available
- hand off to `tools/onboard_driver.py`
If the package manager or installer path is unavailable, stop and give the
exact manual Miniforge command for the current platform.
### 2. Resolve WRDS Scope Once
If the user already answered in chat, pass that through to the driver. If not,
ask once:
- `Do you have a WRDS account and want it configured now?`
Outcomes:
- `yes`: collect username when needed, create WRDS files, and run live WRDS checks
- `no`: skip WRDS setup entirely
- later / declined: also skip WRDS setup entirely
WRDS is optional. Lack of a WRDS account must not make onboarding fail.
### 3. Audit With The Shared Engine
Once Python exists, run the shared audit:
```bash
"<PYTHON>" tools/bootstrap.py audit --json --wrds yes|no
```
Read the audit output and summarize the gaps before changing anything.
### 4. Execute The Bootstrap Plan
Read `bootstrap_plan.steps` from the audit payload and execute each step with
`auto_run=true` for the current shell in order.
The plan is the source of truth for:
- blocking base-repo setup
- optional WRDS setup
- optional writing and R setup
- `tools/bootstrap.py apply`
- the final rerun of `tools/bootstrap.py audit`
If direct command execution is not available because you are running in a plain
local terminal without agent approvals, you may use the best-effort convenience
fallback:
```bash
"<PYTHON>" tools/bootstrap.py repair --write-canonical-state --wrds yes|no
```
### 5. Manual Gaps The Shared Engine Cannot Finish Alone
If the bootstrap plan or fallback repair step cannot install Python packages automatically:
```bash
# With uv (preferred):
uv pip install --no-compile --python "<PYTHON>" pandas psycopg2-binary pyarrow numpy matplotlib statsmodels
# Without uv:
"<PYTHON>" -m pip install --no-compile pandas psycopg2-binary pyarrow numpy matplotlib statsmodels
```
If the bootstrap plan or fallback repair step cannot reinstall repo packages automatically:
```bash
# With uv (preferred):
uv pip install --no-compile --python "<PYTHON>" -e .
cd packages/PyBondLab && uv pip install --no-compile --python "<PYTHON>" -e ".[performance]"
# Without uv:
"<PYTHON>" -m pip install --no-compile -e .
cd packages/PyBondLab && "<PYTHON>" -m pip install --no-compile -e ".[performance]"
```
If `psql` is missing and the user said `no` to WRDS, onboarding can still be
complete. `psql` is only needed for WRDS data extraction.
If the user wants WRDS access later, recommend:
- **Windows**: Download the PostgreSQL zip archive from postgresql.org and extract to `~/tools/pgsql/` (the probe already checks this path).
- **macOS**: `brew install libpq`
- **Linux**: `apt install postgresql-client` or `dnf install postgresql`
Then rerun:
```bash
"<PYTHON>" tools/bootstrap.py audit --wrds yes
```
> **NEVER use conda to install psql, PostgreSQL, LaTeX, or other system tools.**
> Conda's dependency solver hangs on these packages and can corrupt the Python
> environment. Conda is for Python packages only.
If WRDS is enabled and files are missing, create or repair:
1. `~/.pg_service.conf`
2. `~/.pgpass`
3. `~/.ssh/config` entry for `Host wrds` if SSH or TAQ workflows are needed
Use the username from `$ARGUMENTS` if provided, otherwise ask once. If
`~/.pgpass` is missing, ask for the WRDS password and do not echo it back.
Prefer the shared helper:
```bash
AI_ASSET_PRICING_WRDS_PASSWORD="<SECRET>" "<PYTHON>" tools/bootstrap.py wrds-files --username THEIR_USERNAME
```
> **DUO 2FA:** The first `psql service=wrds` connection from a new IP triggers
> a DUO push notification. Tell the user to check their phone and approve it.
> The connection will time out if not approved.
When testing WRDS connectivity, use a date range guaranteed to have data (for
example 2022). Do not use the current year. A query returning 0 rows is not a
valid connectivity confirmation.
Example:
```bash
psql service=wrds -c "SELECT COUNT(*) FROM crsp.dsi WHERE date >= '2022-01-01' AND date < '2023-01-01';"
```
Expected result: about 251 rows.
### 6. Refresh Local Files Only
If you only need to refresh canonical local state after environment changes, run:
```bash
"<PYTHON>" tools/bootstrap.py apply
```
This writes or refreshes canonical external files:
- `local_env.md`
- `claude.local.md`
- `settings.local.json`
### 7. Final Summary
End with a short status table covering:
- base repo
- WRDS
- writing
- R
- Python
- repo packages
If WRDS shows as skipped because the user has no account, say clearly that
onboarding is still complete once the base repo is ready.
Then list the files written and any remaining manual steps.
### Post-Onboard Note
Tools like `psql` may not be on the shell `PATH` even when installed. After
onboarding, always use the absolute paths recorded in canonical local state
(or a repo-root compatibility shim if one was explicitly generated) rather
than bare command names. The bootstrap engine discovers these paths
automatically and writes them to the local files.
---
> Source: [Alexander-M-Dickerson/ai-asset-pricing](https://github.com/Alexander-M-Dickerson/ai-asset-pricing) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
Sections and files
Listed in source order.
sections -> Hard Rules → Workflow → 1. Start With The Shell Entry Point → 2. Resolve WRDS Scope Once → 3. Audit With The Shared Engine → 4. Execute The Bootstrap Plan
terms -> Windows · macOS · Linux · NEVER use conda to install psql, PostgreSQL, LaTeX, or other system tools. · DUO 2FA
files/cmd -> tools/onboard.ps1 · tools/onboard.sh · tools/onboard_driver.py · tools/bootstrap.py · Scanning your environment... · Testing WRDS connectivity... · psql · python
body sha256 -> 6608e5a7edb5
Hard Rules
Print
Scanning your environment...before discovery. PrintTesting WRDS connectivity...before livepsqlchecks. Never assume barepythonor barepipare valid on Windows. Preferuv pip install --python "<PYTHON>"when uv is available; fall back to"<PYTHON>" -m pip install. Prefertools/bootstrap.py audit, the emittedbootstrap_plan, andtools/bootstrap.py applyover ad hoc local-file generation.1. Start With The Shell Entry Point
Use the repo-local shell entrypoint, not
tools/bootstrap.pydirectly, when the machine may not have Python yet. Those entrypoints should: find a usable Python 3.11+ interpreter install Miniforge automatically when no acceptable Python exists and a2. Resolve WRDS Scope Once
If the user already answered in chat, pass that through to the driver. If not, ask once:
Do you have a WRDS account and want it configured now?Outcomes:yes: collect username when needed, create WRDS files, and run live WRDS checks3. Audit With The Shared Engine
Once Python exists, run the shared audit: Read the audit output and summarize the gaps before changing anything.
4. Execute The Bootstrap Plan
Read
bootstrap_plan.stepsfrom the audit payload and execute each step withauto_run=truefor the current shell in order. The plan is the source of truth for: blocking base-repo setup optional WRDS setup