​
Project Operations

​
Purpose

Use this page when the task is about operating the project as a whole rather than editing one small feature in isolation. This page is for:
  • leads and analysts who need to understand how the project is organized
  • engineers who need to know which repo or runtime surface to change
  • AI agents that need a practical operating model before they edit code, docs, or deployment assets

​
Project Surfaces

OneLink currently spans these operational surfaces:
  • application code repository: onelink
  • documentation repository mounted as onelink/docs
  • versioned project skill source under onelink/.codex/skills
  • local Codex skill library under $CODEX_HOME/skills
  • deployment assets under deployment/, docker/, and docker-compose*.yaml
  • API contract surfaces under swagger/ and onelink/docs/openapi/
Use Repository Map for exact directory placement.

​
Local Runtime Modes

​
Dev Lite

Default for most work:
  • Rails server
  • Vite dev server
  • no Sidekiq
Primary entrypoints:
  • pnpm dev:lite
  • foreman start -f ./Procfile.dev-lite
  • ./bin/dev-lite-restart
Use this mode when:
  • you are editing controller/model/service happy paths
  • you are editing most dashboard/frontend work
  • the task does not depend on async jobs or background processing

​
Full Dev

Use when jobs or async flows matter:
  • pnpm dev
  • overmind start -f ./Procfile.dev
This adds:
  • Sidekiq
  • the full async runtime expected by job-driven flows

​
Docker-Based Local Runtime

Use when you need a containerized local environment or to check compose-based behavior. Relevant files:
  • docker-compose.yaml
  • docker-compose.test.yaml
  • docker-compose.production.yaml
  • docker/dockerfiles/*

​
Primary Operational Files

These files control most project behavior:
  • Procfile.dev-lite
  • Procfile.dev
  • config/routes.rb
  • config/features.yml
  • config/agents/tools.yml
  • config/initializers/*
  • vite.config.mts
  • tailwind.config.js
  • config/sidekiq.yml
  • config/puma.rb
  • docker-compose.yaml
  • deployment/setup_20.04.sh
  • deployment/nginx_chatwoot.conf

​
Git and Delivery Model

​
Main Application Repo

Use these rules:
  • base branch: onelink-main
  • writable remote: origin
  • upstream sync source: upstream
  • push over SSH

​
Documentation Repo

Docs are a separate Git repository mounted as a submodule:
  • content lives in onelink-docs
  • the app repo stores only the docs submodule pointer
Flow:
  1. commit docs content in onelink/docs
  2. push the docs repo
  3. update the submodule pointer in the parent onelink repo if needed

​
Skill Source

Skills now have two locations:
  • versioned project source in onelink/.codex/skills
  • installed runtime copy in $CODEX_HOME/skills
Flow:
  1. edit and commit the versioned project copy in onelink/.codex/skills
  2. sync to the installed Codex copy with ./.codex/scripts/sync-skills.sh to-codex-home
  3. if a local runtime skill changed first, sync it back with ./.codex/scripts/sync-skills.sh from-codex-home

​
Upstream Sync

Use dedicated sync branches when bringing upstream changes into the fork. Do not treat develop in this fork as the product base branch. Use Upstream Sync for the exact process.

​
API and Documentation Pipeline

The API documentation pipeline has two connected layers:
  1. swagger/
    • source fragments and generated OpenAPI JSON in the main app repo
  2. onelink/docs/openapi/
    • local OpenAPI files consumed by Mintlify
Flow:
  1. change the API behavior
  2. update swagger/
  3. run bundle exec rake swagger:build
  4. from onelink/docs, run ./scripts/sync-openapi-from-onelink.sh
  5. commit docs-side OpenAPI changes in onelink-docs
Use API Documentation and Docs Repository Workflow together.

​
Deployment Surfaces

OneLink currently has multiple deployment-related surfaces:
  • deployment/
    • VM/systemd/nginx install and upgrade assets
  • docker-compose*.yaml
    • local and production-like container setups
  • docs/self-hosted/
    • human-readable deployment and operational docs
  • environment config:
    • config/environments/*.rb
    • .env
    • config/app.yml
    • config/storage.yml
Use the deployment docs when the task is about runtime operation, not only code structure.

​
Human and Agent Coordination

For coordinated work across people and AI agents:
  • classify the task first:
    • backend
    • frontend
    • api
    • integrations
    • captain/ai
    • docs
    • deployment
    • gitops/upstream
  • load the matching docs pages before editing
  • use the specialized skill for that surface when available
  • keep repo boundaries clean:
    • app code commit in onelink
    • docs content commit in onelink-docs
    • versioned skill changes commit in onelink/.codex/skills

​
If the task is mainly GitHub, branch, or upstream-sync work

  • use the onelink-gitops skill
  • use onelink-main as the base branch
  • use sync/... branches only for upstream intake
Use AI Agent Operating Model and Skill Map for the working rules.

​
Quick Decision Rules

​
If the task changes runtime behavior

  • edit app code in onelink
  • add or update specs where appropriate
  • update docs if product behavior or architecture meaning changed

​
If the task changes API contracts

  • update controllers/builders/specs
  • update swagger/
  • sync docs OpenAPI files

​
If the task changes only docs

  • edit onelink/docs
  • commit inside the docs repo first

​
If the task changes how the project is run or deployed

  • edit deployment/runtime config
  • update self-hosted docs and project operations docs if the operator workflow changed