[codex] Polish skill-only handoff docs

.github/CONTRIBUTING.md

@@ -1,36 +1,34 @@
 # Contributing
 
-Thanks for taking the time to contribute! Please follow these guidelines.
+This branch ships the handoff skills and a shell installer.
 
 ## Branching
 
-- Branch off `main` for all changes
-- Use descriptive branch names: `feat/add-auth`, `fix/null-pointer`, `chore/update-deps`
+- Branch off `master` for skill and installer changes.
+- Keep changes focused and reviewable.
 
-## Commit Messages
+## Verification
 
-Follow [Conventional Commits](https://www.conventionalcommits.org/):
+Before opening a pull request, run:
 
+```bash
+bash -n install.sh
+tmp="$(mktemp -d)"
+./install.sh both --home "$tmp" --mode copy
 ```
-feat: add user login endpoint
-fix: handle empty response from model
-chore: bump dependencies
-docs: update API reference
-```
-
-## Pull Requests
 
-- Keep PRs small and focused (one concern per PR)
-- Fill out the PR template fully
-- All CI checks must pass before requesting review
-- At least 1 approval required to merge
+Then confirm these files exist:
 
-## Code Style
-
-- Follow the `.editorconfig` settings
-- Run the linter before pushing
-- Write tests for new features
+```text
+$tmp/.codex/skills/handoff/SKILL.md
+$tmp/.codex/skills/get-handoff/SKILL.md
+$tmp/.claude/skills/handoff/SKILL.md
+$tmp/.claude/skills/get-handoff/SKILL.md
+```
 
-## Reporting Issues
+## Pull Requests
 
-Use the issue templates provided — bug reports and feature requests have separate forms.
+- Fill out the PR template.
+- Include the verification you ran.
+- Do not commit local `.handoff/`, `.omx/`, `.omc/`, or runtime install
+  directories.

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,29 +1,29 @@
 ## What does this PR do?
 
-<!-- Brief description of the change and why it's needed -->
+<!-- Brief description of the skill or installer change and why it is needed. -->
 
 ## Type of change
 
-- [ ] Bug fix
-- [ ] New feature
-- [ ] Refactor / cleanup
-- [ ] Docs / chore
+- [ ] Skill behavior
+- [ ] Installer
+- [ ] Documentation
+- [ ] GitHub metadata / CI
 - [ ] Breaking change
 
 ## Related issues
 
 Closes #<!-- issue number -->
 
-## Testing
+## Verification
 
-<!-- How was this tested? What should reviewers check? -->
+<!-- Include the commands you ran and what reviewers should check. -->
 
-- [ ] Unit tests added / updated
-- [ ] Manually tested
+- [ ] `bash -n install.sh`
+- [ ] `./install.sh both --home "$(mktemp -d)" --mode copy`
+- [ ] Manually reviewed installed `SKILL.md` files
 
 ## Checklist
 
-- [ ] My code follows the project's style guidelines
-- [ ] I've reviewed my own diff
-- [ ] I've added comments where the code is non-obvious
-- [ ] No new secrets or credentials committed
+- [ ] The README still matches the install flow
+- [ ] Skill files remain under `skills/<name>/SKILL.md`
+- [ ] No local `.handoff/`, `.omx/`, `.omc/`, `.codex`, or `.claude` state is committed

.github/dependabot.yml

@@ -1,14 +1,5 @@
 version: 2
 updates:
-  - package-ecosystem: pip
-    directory: "/"
-    schedule:
-      interval: weekly
-      day: monday
-    open-pull-requests-limit: 5
-    labels:
-      - dependencies
-
   - package-ecosystem: github-actions
     directory: "/"
     schedule:

.github/workflows/ci.yml

@@ -11,31 +11,34 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  lint:
-    name: LintExpected
+  validate:
+    name: Validate skills and installer
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-
-      - name: Compile Python sources
-        run: python -m compileall src tests
-
-  test:
-    name: TestsExpected
-    runs-on: ubuntu-latest
-    needs: lint
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-
-      - name: Run tests
-        run: PYTHONPATH=src python -m unittest discover -s tests -v
+      - name: Check shell syntax
+        run: bash -n install.sh
+
+      - name: Check skill files
+        run: |
+          test -f skills/handoff/SKILL.md
+          test -f skills/get-handoff/SKILL.md
+          grep -q 'name: handoff' skills/handoff/SKILL.md
+          grep -q 'name: get-handoff' skills/get-handoff/SKILL.md
+
+      - name: Smoke test copy install
+        run: |
+          tmp="$(mktemp -d)"
+          ./install.sh both --home "$tmp" --mode copy
+          test -f "$tmp/.codex/skills/handoff/SKILL.md"
+          test -f "$tmp/.codex/skills/get-handoff/SKILL.md"
+          test -f "$tmp/.claude/skills/handoff/SKILL.md"
+          test -f "$tmp/.claude/skills/get-handoff/SKILL.md"
+
+      - name: Smoke test symlink install
+        run: |
+          tmp="$(mktemp -d)"
+          ./install.sh codex --home "$tmp" --mode symlink
+          test -L "$tmp/.codex/skills/handoff"
+          test -L "$tmp/.codex/skills/get-handoff"

.gitignore

@@ -1,119 +1,33 @@
-# ── Python ──────────────────────────────────────────────
-__pycache__/
-*.py[cod]
-*$py.class
-*.so
-.Python
+# Local runtime state
+.handoff/
+.omx/
+.omc/
+.codex
+.codex/
+.claude
+.claude/
+
+# Build and cache output
 build/
-develop-eggs/
 dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-share/python-wheels/
+.venv/
 *.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-*.pyo
-
-# Virtual environments
-.env
-.venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
-.python-version
 .pytest_cache/
-.mypy_cache/
-.ruff_cache/
-.coverage
-htmlcov/
-
-# ── ML / Data ────────────────────────────────────────────
-*.h5
-*.hdf5
-*.pkl
-*.pickle
-*.pt
-*.pth
-*.onnx
-*.pb
-*.ckpt
-*.safetensors
-data/raw/
-data/processed/
-models/
-checkpoints/
-runs/
-wandb/
-mlruns/
-.neptune/
-lightning_logs/
-
-# Jupyter
-.ipynb_checkpoints/
-*.ipynb
-
-# ── Node / JS ────────────────────────────────────────────
-node_modules/
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-.pnpm-debug.log*
-.yarn/cache
-.yarn/unplugged
-dist/
-.next/
-.nuxt/
-.output/
-.cache/
+__pycache__/
+*.py[cod]
 
-# ── Editors ──────────────────────────────────────────────
+# Editors and OS files
 .idea/
 .vscode/
 *.swp
 *.swo
-*.sublime-project
-*.sublime-workspace
 .DS_Store
 Thumbs.db
 
-# ── Secrets / Credentials ────────────────────────────────
+# Secrets
 .env
 .env.*
 !.env.example
 *.pem
 *.key
-*.p12
-*.pfx
 secrets/
-
-# ── OS ───────────────────────────────────────────────────
-.DS_Store
-.DS_Store?
-._*
-.Spotlight-V100
-.Trashes
-ehthumbs.db
-Thumbs.db
-
-# ── Infra / IaC ──────────────────────────────────────────
-.terraform/
-*.tfstate
-*.tfstate.*
-.terraformrc
-terraform.rc
-.omx/
-
-# ── Local agent / handoff helpers ────────────────────────
-.codex
-.claude/