Engineering foundation: README, CONTRIBUTING, tech stack, ADR template, onboarding, CI placeholder, first engineer role

Sets up the engineering baseline for El Foundation before product work begins.

- README.md: project overview and repo layout
- CONTRIBUTING.md: branch naming, PR process, commit style, definition of done
- docs/engineering/tech-stack.md: frontend, backend, and tooling choices with rationale
- docs/engineering/onboarding.md: 30-day onboarding checklist
- docs/adrs/adr-template.md: decision record template
- .github/workflows/ci.yml: markdown lint + placeholder for TypeScript checks
- docs/engineering/first-engineer-role.md: scope, skills, 30-day priorities, hire recommendation

Co-Authored-By: Paperclip <noreply@paperclip.ing>

.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check markdown formatting
+        uses: DavidAnson/markdownlint-cli2-action@v16
+        with:
+          globs: '**/*.md'
+        continue-on-error: true
+
+  # TODO: Enable once we have a TypeScript project
+  # lint-and-test:
+  #   runs-on: ubuntu-latest
+  #   steps:
+  #     - uses: actions/checkout@v4
+  #     - uses: pnpm/action-setup@v4
+  #     - uses: actions/setup-node@v4
+  #       with:
+  #         node-version: 22
+  #         cache: 'pnpm'
+  #     - run: pnpm install --frozen-lockfile
+  #     - run: pnpm lint
+  #     - run: pnpm typecheck
+  #     - run: pnpm test

CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to El Foundation
+
+## One Task = One Branch = One Owner
+
+Every issue gets its own branch. Branch names follow this pattern:
+
+```
+owner-identifier/short-description
+```
+
+Examples:
+- `cto/ELF-4-engineering-foundation`
+- `eng-1/add-auth-middleware`
+
+## No Direct Commits to `main`
+
+All changes go through a pull request. No exceptions.
+
+## Pull Request Process
+
+1. **Open a PR** from your branch to `main`.
+2. **Fill out the PR template** (risk, rollback, verification).
+3. **Request review** from the relevant owner:
+   - Code changes → another engineer or CTO
+   - UX-facing changes → UXDesigner
+   - Security-sensitive changes → SecurityEngineer
+4. **Address feedback** or escalate disagreements in writing.
+5. **Ship on green.** Once CI passes and review is approved, the owner merges.
+
+## Commit Messages
+
+Commit messages explain **why**, not what. The diff shows what changed; the message explains the reasoning.
+
+Good:
+```
+Add rotating refresh tokens
+
+Using a rotating refresh token strategy prevents replay attacks
+and gives us a clean theft-detection signal. See ADR-003.
+
+Co-Authored-By: Paperclip <noreply@paperclip.ing>
+```
+
+Bad:
+```
+Update auth.ts
+```
+
+## Code Style
+
+- TypeScript strict. No `any` unless explicitly approved — use `unknown` + narrowing.
+- Keep `lib/` (pure logic) and `services/` (I/O, DB, network) separate.
+- Prefer small modules over clever abstractions.
+- No comments unless the code is genuinely non-obvious or there is a real `// FIXME`.
+- No defensive try/catch around things that should not fail. Let it throw.
+- Server Components by default; reach for `"use client"` only when state, effects, or browser APIs are needed.
+
+## Definition of Done
+
+A task is not done until **all** of the following are true:
+
+1. Code is written and reviewed.
+2. Tests pass. CI is green.
+3. Documentation is updated.
+4. No secrets in plain text.
+5. User-facing changes are validated.
+6. Rollback path is known.
+7. Handoff is clean — follow-up work is captured in a new issue.
+
+## Security
+
+- Never commit secrets, credentials, or customer data.
+- Security-sensitive changes (auth, crypto, secrets, permissions) require SecurityEngineer review before merging.
+- Report vulnerabilities to the CTO immediately.
+
+## Questions?
+
+Open an issue or ask in the project channel. Async-first: write it down.

README.md

@@ -0,0 +1,38 @@
+# El Foundation
+
+Engineering repository for El Foundation.
+
+## About
+
+El Foundation builds institutions that outlast their founders. We create technology and organizations that compound in value over time. This repository is the source of truth for our engineering work.
+
+## Getting Started
+
+1. Read the [company charter](docs/company/charter.md) to understand why we exist.
+2. Read the [operating model](docs/company/operating-model.md) to understand how decisions are made.
+3. Read [CONTRIBUTING.md](CONTRIBUTING.md) before making any changes.
+
+## Repository Layout
+
+```
+├── .github/workflows/    # CI/CD definitions
+├── docs/
+│   ├── company/          # Founding documents (charter, org, etc.)
+│   ├── engineering/      # Engineering standards and decisions
+│   └── adrs/             # Architecture Decision Records
+├── apps/                 # Application code (TBD — created when product work begins)
+├── packages/             # Shared libraries and packages
+└── scripts/              # Automation and utility scripts
+```
+
+## Technology Stack
+
+See [docs/engineering/tech-stack.md](docs/engineering/tech-stack.md) for current choices and rationale.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+Proprietary — All rights reserved.

docs/adrs/adr-template.md

@@ -0,0 +1,51 @@
+# ADR-XXX: Title
+
+## Status
+
+- Proposed
+- Accepted
+- Deprecated
+- Superseded by [ADR-YYY](adr-YYY.md)
+
+## Context
+
+What is the problem or opportunity we are addressing? What forces are at play?
+
+## Decision
+
+What are we doing? Be specific.
+
+## Consequences
+
+### Positive
+
+- Benefit 1
+- Benefit 2
+
+### Negative / Risks
+
+- Risk 1
+- Risk 2
+
+## Alternatives Considered
+
+### Option A: [Name]
+
+- Pros: ...
+- Cons: ...
+- Why rejected: ...
+
+### Option B: [Name]
+
+- Pros: ...
+- Cons: ...
+- Why rejected: ...
+
+## Rollback Plan
+
+If this decision proves wrong, how do we undo it?
+
+## Related
+
+- [ADR-YYY](adr-YYY.md)
+- [PR #123](../../pull/123)

docs/engineering/first-engineer-role.md

@@ -0,0 +1,70 @@
+# Role Definition: First Software Engineer
+
+## Context
+
+El Foundation has established its charter, operating model, and engineering baseline. We are pre-product but have a clear technical direction. The first engineer will work directly with the CTO to build the initial product and set the engineering culture for every hire that follows.
+
+## What They Will Own
+
+- **Product implementation.** Write the first lines of production code. Own features end-to-end from task assignment to merge.
+- **Technical foundation.** Help solidify the stack, tooling, and conventions. The code you write sets the standard.
+- **Quality bar.** Write tests, review PRs, and catch regressions before they reach users.
+- **Documentation.** If it is not written down, it does not exist. Document APIs, runbooks, and decisions as you go.
+- **Production reliability.** Once we have users, own on-call rotation with the CTO and ensure systems stay healthy.
+
+## Technical Skills Required
+
+### Must-Have
+
+- **TypeScript** — strong typed-language fundamentals, comfortable with strict mode
+- **React / Next.js** — experience with App Router, Server Components, and modern React patterns
+- **Relational databases** — schema design, query optimization, migration discipline (PostgreSQL preferred)
+- **Git and GitHub** — branching, rebasing, PR discipline, code review
+- **Testing mindset** — writes tests as a default, not an afterthought
+
+### Nice-to-Have
+
+- **Prisma ORM** — or similar type-safe ORM experience
+- **Tailwind CSS** — or strong utility-first CSS experience
+- **Monorepo tooling** — Turborepo, Nx, or similar
+- **Cloud infrastructure** — Vercel, AWS, Fly.io, or similar
+- **Authentication / security** — OAuth, JWT, session management
+- **Mongolian language or market context** — our early users are likely in Mongolia
+
+## Attributes We Value
+
+- **Slope over intercept.** We care more about how fast you learn than what you already know.
+- **Writes things down.** Async-first communication. Clear documentation. Decision records.
+- **Disagrees and commits.** Healthy dissent, then full commitment once a decision is made.
+- **Protects focus.** Ruthless prioritization. Says no to multitasking.
+- **Pulls for bad news.** Surfaces problems early. Does not hide blockers.
+
+## First 30-Day Priorities
+
+| Week | Focus | Deliverable |
+|---|---|---|
+| 1 | Onboard and ship a small fix | Merged PR, environment verified |
+| 2 | Build first feature slice | Working code in staging |
+| 3 | Establish testing pattern | Test coverage for new code, CI green |
+| 4 | Document and refine | Updated docs, onboarding feedback, first ADR contribution |
+
+## Reporting
+
+- **Reports to:** CTO
+- **Peers:** None yet — you are the first IC
+- **Growth path:** Senior Engineer → Staff Engineer → Engineering Lead as the team scales
+
+## Compensation & Logistics
+
+- **Decision owner:** CEO (pending approval)
+- **Budget:** To be confirmed by CEO
+- **Location:** Remote / async-first
+- **Start date:** As soon as approved and hired
+
+## Recommendation
+
+**Hire a mid-level full-stack engineer with strong TypeScript and Next.js experience.** They should have shipped production code independently and be comfortable with ambiguity. A senior engineer would be ideal but may be overkill for our current stage and budget. A junior engineer would require too much hands-on guidance from the CTO, slowing both product velocity and hiring velocity.
+
+**Suggested title:** Software Engineer  
+**Suggested level:** Mid-level (2–5 years shipping production code)  
+**Priority:** High — we cannot build product without an engineer.

docs/engineering/onboarding.md

@@ -0,0 +1,43 @@
+# Engineer Onboarding
+
+## Before Day 1
+
+- [ ] Access to GitHub org granted
+- [ ] Access to Paperclip workspace granted
+- [ ] Added to project channels / async standup
+
+## Day 1: Context
+
+- [ ] Read the [company charter](../company/charter.md)
+- [ ] Read the [operating model](../company/operating-model.md)
+- [ ] Read [ways of working](../company/ways-of-working.md)
+- [ ] Read [how we decide](../company/how-we-decide.md)
+- [ ] Read [CONTRIBUTING.md](../../CONTRIBUTING.md)
+- [ ] Read [tech-stack.md](tech-stack.md)
+- [ ] Introduce yourself in the team channel (async written standup format)
+
+## Day 2–3: Environment
+
+- [ ] Clone the repo
+- [ ] Install dependencies (`pnpm install` when package.json exists)
+- [ ] Run the dev server locally
+- [ ] Verify you can run tests
+- [ ] Verify you can run lint
+- [ ] Open your first PR (a README typo fix or doc improvement counts)
+
+## Week 1: First Task
+
+- [ ] Pick up a `good first issue` or grab a task from the backlog with CTO approval
+- [ ] Follow the full task lifecycle: branch → PR → review → merge
+- [ ] Shadow one code review as a reviewer (even if just observing)
+
+## First 30 Days
+
+- [ ] Ship at least one meaningful change to production (or equivalent if pre-launch)
+- [ ] Write or update one piece of documentation
+- [ ] Attend (async) one decision review or ADR discussion
+- [ ] Provide feedback on the onboarding process itself
+
+## Questions?
+
+Ask the CTO or post in the project channel. Async-first: write it down.

docs/engineering/tech-stack.md

@@ -0,0 +1,49 @@
+# Technology Stack
+
+## Overview
+
+These choices were made by the CTO on 2026-06-22, aligned with the company charter and operating principles. They are reversible within a day for local development, but would require migration effort once production data exists. All choices default to boring, well-supported technology over novelty.
+
+## Frontend
+
+| Layer | Choice | Rationale |
+|---|---|---|
+| Framework | Next.js (App Router) | Full-stack React with SSR/SSG, API routes, and a large ecosystem. App Router is the stable future path. |
+| Language | TypeScript (strict) | Catches entire classes of bugs at build time. Strict mode is non-negotiable. |
+| Styling | Tailwind CSS | Utility-first, colocated with components, no separate CSS files to maintain. |
+| UI Components | shadcn/ui pattern | Copy-paste components we own and can customize. No opaque UI library dependencies. |
+
+## Backend & Data
+
+| Layer | Choice | Rationale |
+|---|---|---|
+| Database | PostgreSQL | Proven, feature-rich, great ORM support. Our relational data model fits it well. |
+| ORM | Prisma | Type-safe queries, excellent migration tooling, good DX. |
+| Auth | NextAuth.js | Battle-tested, supports many providers, integrates cleanly with Next.js. |
+| Storage | Cloudflare R2 | S3-compatible, zero egress fees, good for file uploads and static assets. |
+| Payments | TBD | Will evaluate when we have a revenue model. |
+
+## Tooling
+
+| Layer | Choice | Rationale |
+|---|---|---|
+| Package Manager | pnpm | Fast, disk-space efficient, strict `node_modules` layout avoids phantom dependencies. |
+| Monorepo | Turborepo (when needed) | Caching and task orchestration. Only adopt when we have >1 app or shared package. |
+| CI/CD | GitHub Actions | Native GitHub integration, free for public repos, cheap for private. |
+| Lint | ESLint + Prettier | Standard, autofixable, low-friction. |
+
+## Principles
+
+- **Server Components by default.** Reach for `"use client"` only when the component actually needs state, effects, or browser APIs.
+- **Pure logic in `lib/`, I/O in `services/`.** Business logic does not import from `next/server` or call `fetch` directly.
+- **Store money as integers.** MNT (Mongolian Tugrik) in smallest unit. Format on display.
+- **Observability before optimization.** Measure before fixing. No tuning without metrics.
+- **Idempotency.** Operations should be safe to retry. Infrastructure changes should be reproducible.
+
+## Open Decisions
+
+| Decision | Status | Owner | Blocker |
+|---|---|---|---|
+| Hosting provider (Vercel, Fly, AWS?) | Open | CTO | Need product requirements and traffic estimates |
+| Monitoring / alerting stack | Open | CTO | Need hosting decision |
+| CDN / edge strategy | Open | CTO | Need hosting decision |