[codex] Improve onboarding, portability, and failure visibility

.env.example

@@ -0,0 +1,12 @@
+# Optional: override where Nightshift stores sqlite/reports/state
+NIGHTSHIFT_DATA_DIR=~/.nightshift
+
+# Optional: explicit config file path
+# NIGHTSHIFT_CONFIG_FILE=~/.nightshift/config.toml
+
+# Optional: project alias path overrides (examples)
+# NIGHTSHIFT_PROJECT_OPSORCHESTRA=~/Projects/opsorchestra
+# NIGHTSHIFT_PROJECT_GHOST_SENTRY=~/Projects/anor/ghost-sentry
+
+# Optional: notifications
+# SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,59 @@
+name: Bug report
+description: Report a bug in Nightshift runtime, API, plugin, or docs.
+title: "[bug] "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What happened?
+      placeholder: Clear description of the issue.
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: Exact commands/actions to reproduce.
+      placeholder: |
+        1. ...
+        2. ...
+        3. ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: env
+    attributes:
+      label: Environment
+      description: Include OS, Python, OpenCode, and install method.
+      placeholder: |
+        - OS:
+        - Python:
+        - OpenCode:
+        - Nightshift:
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / output
+      description: Paste relevant logs, stack traces, and command output.
+      render: shell

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,32 @@
+name: Feature request
+description: Propose an improvement for users or contributors.
+title: "[feature] "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem statement
+      description: What user pain does this solve?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What should be added or changed?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+
+  - type: textarea
+    id: impact
+    attributes:
+      label: Impact
+      description: Who benefits and how?
+      placeholder: Users, contributors, maintainers, etc.

.github/pull_request_template.md

@@ -0,0 +1,27 @@
+## Summary
+
+Describe what changed and why.
+
+## Problem
+
+What user/contributor issue does this PR address?
+
+## Root Cause
+
+What caused the issue?
+
+## Fix
+
+How does this PR resolve it?
+
+## Validation
+
+List checks run locally:
+
+- [ ] `python -m pytest -q`
+- [ ] `python -m compileall -q src tests`
+- [ ] `cd plugin && bun run typecheck`
+
+## Notes
+
+Any follow-ups, risks, or migration notes.

ARCHITECTURE.md

@@ -0,0 +1,51 @@
+# Architecture
+
+Nightshift has three primary layers:
+
+1. `src/cli.py`: local command interface (`nightshift ...`).
+2. `src/server.py`: FastAPI server and dashboard/API bridge.
+3. `src/runner.py` + `src/task_queue.py`: execution loop and persistence.
+
+## Runtime Flow
+
+1. A run is started via CLI (`nightshift start ...`) or API (`POST /start`).
+2. `NightshiftRunner` creates a run in sqlite and generates task rows.
+3. Tasks are prioritized (`SmartPrioritizer`) and executed in order.
+4. Agent calls are sent through `OpencodeAgentClient`.
+5. Findings/errors are persisted in sqlite and rendered into reports.
+6. Report and diff artifacts are written under `~/.nightshift/reports`.
+
+## Persistence Model
+
+- Database: `~/.nightshift/nightshift.db` (or `NIGHTSHIFT_DATA_DIR` override).
+- Core tables:
+  - `runs`
+  - `tasks` (scoped by `run_id`)
+  - `findings`
+
+Run scoping is important: status, reports, and diffs should query by run context to avoid cross-run leakage.
+
+## Configuration Sources
+
+Order of precedence:
+
+1. Explicit command/API arguments
+2. Environment variables
+3. `config.toml` (`~/.nightshift/config.toml` by default)
+4. Built-in defaults
+
+Key config behavior is implemented in `src/config.py`.
+
+## Model Selection
+
+`src/model_manager.py` resolves the failover chain by:
+
+1. Taking configured preferred models.
+2. Discovering currently available OpenCode models (`opencode models`).
+3. Keeping preferred models that exist.
+4. Falling back to a ranked discovered chain when needed.
+
+## Frontend
+
+`src/dashboard.html` is a static UI served from `/` by FastAPI.
+It polls `/status`, `/models`, `/reports`, and `/schedules`.

CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing To Nightshift
+
+Thanks for contributing.
+
+## Local Setup
+
+```bash
+git clone <your-fork-or-upstream-url>
+cd nightshift
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -e '.[dev]'
+cd plugin && bun install && cd ..
+```
+
+## Recommended First Run
+
+```bash
+nightshift init
+nightshift doctor
+```
+
+## Development Commands
+
+```bash
+python -m pytest -q
+python -m compileall -q src tests
+cd plugin && bun run typecheck
+```
+
+## Pull Requests
+
+- Keep PRs focused and small when possible.
+- Include validation notes (tests/checks run).
+- Update docs when behavior or interfaces change.
+- Prefer portable paths and avoid user-specific absolute paths.
+
+## Branch Naming
+
+- Suggested: `codex/<short-description>` for feature branches.

README.md

@@ -8,13 +8,14 @@ Nightshift is an overnight autonomous research agent designed for **OpenCode**.
 ## Features
 
 - **Autonomous Research**: Deep dives into codebases without manual intervention.
-- **Multi-Model Failover**: Intelligent failover chain across Claude Opus, GPT-5, and Gemini models to bypass rate limits and optimize performance.
+- **Multi-Model Failover**: Automatically discovers available OpenCode models and builds a resilient fallback chain.
 - **Comprehensive Reports**: Generates detailed HTML research reports and differential reports comparing changes between runs.
 - **OpenCode Integration**: A dedicated plugin that lets you control Nightshift directly from your editor.
 - **Smart Scheduling**: Built-in support for daily research tasks using cron or macOS launchd.
 - **GitHub Integration**: Automatically creates issues for critical findings.
 - **Notifications**: Real-time alerts via Slack or custom webhooks.
 - **Web Dashboard**: Interactive dashboard for monitoring runs and viewing findings.
+- **Setup UX**: Built-in `nightshift init` and `nightshift doctor` commands for first-run setup and troubleshooting.
 
 ## Installation
 
@@ -40,17 +41,27 @@ To load the plugin in OpenCode, point your plugin configuration to the `plugin/i
 
 ## Quick Start
 
-1. **Start the API Server**:
+1. **Initialize local config**:
+   ```bash
+   nightshift init
+   ```
+
+2. **Validate setup**:
+   ```bash
+   nightshift doctor
+   ```
+
+3. **Start the API Server**:
    ```bash
    nightshift serve
    ```
 
-2. **Run a Research Task**:
+4. **Run a Research Task**:
    ```bash
-   nightshift start opsorchestra ghost-sentry --duration 8.0
+   nightshift start opsorchestra --duration 8.0
    ```
 
-3. **View the Report**:
+5. **View the Report**:
    ```bash
    nightshift report
    ```
@@ -60,6 +71,8 @@ To load the plugin in OpenCode, point your plugin configuration to the `plugin/i
 The `nightshift` command provides several subcommands:
 
 - `start [PROJECTS]...`: Start a research run on specified projects or paths.
+- `init`: Create a starter `config.toml` in your Nightshift data directory.
+- `doctor`: Validate OpenCode/GitHub/config/dependency setup and show fix hints.
 - `serve`: Start the HTTP API server (default port: 7890).
 - `status`: Show current run status and model availability.
 - `report`: Open the latest research report in your browser.
@@ -109,18 +122,50 @@ curl http://127.0.0.1:7890/status
 
 Nightshift stores its data in `~/.nightshift`.
 
+### Config File
+
+Nightshift reads optional user config from:
+
+- `~/.nightshift/config.toml`
+- or `NIGHTSHIFT_CONFIG_FILE` if set
+
+Create a starter config with:
+
+```bash
+nightshift init
+```
+
+Example:
+
+```toml
+[defaults]
+duration_hours = 8.0
+priority_mode = "balanced"
+open_report_in_browser = true
+
+[projects]
+backend = "/path/to/backend"
+frontend = "/path/to/frontend"
+
+[models]
+preferred = ["openai/gpt-5.2", "google/antigravity-gemini-3-pro-high"]
+```
+
 ### Environment Variables
 - `NIGHTSHIFT_DATA_DIR`: Override the default data directory.
+- `NIGHTSHIFT_CONFIG_FILE`: Override the default config path.
 - `NIGHTSHIFT_PROJECT_OPSORCHESTRA`: Override default path for the `opsorchestra` alias.
 - `NIGHTSHIFT_PROJECT_GHOST_SENTRY`: Override default path for the `ghost-sentry` alias.
 - `SLACK_WEBHOOK_URL`: Default webhook for notifications.
 
-### Model Failover Chain
-Nightshift automatically cycles through the following models:
-1. Claude 4.5 Thinking (High)
-2. GPT-5.2
-3. Gemini 3 Pro (High)
-4. Gemini 3 Flash
+See `.env.example` for a complete starter environment file.
+
+### Model Selection
+
+Nightshift tries to:
+1. Use preferred models from `config.toml` (if set).
+2. Keep only models available in your current OpenCode environment.
+3. Auto-rank discovered models when preferred models are unavailable.
 
 ## Architecture
 
@@ -129,5 +174,12 @@ Nightshift consists of three main components:
 2. **API Server (FastAPI)**: Provides a bridge between the core engine and external tools.
 3. **OpenCode Plugin (TypeScript)**: Exposes research tools directly within the developer environment.
 
+For deeper implementation details, see `ARCHITECTURE.md`.
+
+## Contributing
+
+Forks and external contributions are welcome.
+See `CONTRIBUTING.md` for local setup, dev commands, and PR expectations.
+
 ---
 Built for autonomous engineering.