Add docs and a Makefile, and bring local Postgres to 17

.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[*.py]
+indent_size = 4
+
+[Makefile]
+indent_style = tab
+
+[*.md]
+trim_trailing_whitespace = false

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,34 @@
+name: Bug report
+description: Something in TandemCode does not work as it should.
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: What you did, what you expected, and what you saw instead.
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Open a room
+        2. ...
+    validations:
+      required: true
+  - type: dropdown
+    id: where
+    attributes:
+      label: Where
+      options:
+        - tandemcode.space
+        - A local checkout
+    validations:
+      required: true
+  - type: textarea
+    id: details
+    attributes:
+      label: Browser, logs, screenshots
+      description: Browser and OS, any errors from the browser console, and API or runner logs if you run it locally.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/naman0r/tandemcode/security/advisories/new
+    about: Please report vulnerabilities privately, not in a public issue. See SECURITY.md.

.github/ISSUE_TEMPLATE/problem.yml

@@ -0,0 +1,31 @@
+name: Problem proposal
+description: Suggest a practice problem. If you can write it yourself, CONTRIBUTING.md shows how.
+labels: [problem]
+body:
+  - type: input
+    id: title
+    attributes:
+      label: Problem
+      placeholder: Move Zeroes
+    validations:
+      required: true
+  - type: textarea
+    id: statement
+    attributes:
+      label: Statement
+      description: The task in your own words, with one example input and output. Do not paste text from other sites.
+    validations:
+      required: true
+  - type: dropdown
+    id: difficulty
+    attributes:
+      label: Difficulty
+      options: [easy, medium, hard]
+    validations:
+      required: true
+  - type: checkboxes
+    id: pr
+    attributes:
+      label: Contribution
+      options:
+        - label: I would like to open the pull request for this myself.

.github/PULL_REQUEST_TEMPLATE.md

@@ -5,3 +5,7 @@
 ## How this was verified
 
 <!-- Be specific about what you ran and what you did not check. -->
+
+## Docs
+
+<!-- If this changes how something works, which page in docs/ did you update? Write "none needed" if it does not. -->

.github/dependabot.yml

@@ -0,0 +1,27 @@
+# Monthly and grouped, so updates arrive as one pull request per ecosystem.
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /apps/web
+    schedule:
+      interval: monthly
+    groups:
+      web:
+        patterns: ["*"]
+    ignore:
+      # Pinned on purpose. Upgrade it by hand and check the shared editor.
+      - dependency-name: monaco-editor
+  - package-ecosystem: pip
+    directory: /apps/backend
+    schedule:
+      interval: monthly
+    groups:
+      backend:
+        patterns: ["*"]
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    groups:
+      actions:
+        patterns: ["*"]

.github/workflows/docs.yml

@@ -0,0 +1,21 @@
+name: Docs
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # Relative links only: a moved or deleted file fails the build, and an
+      # outside site being down does not.
+      - uses: lycheeverse/lychee-action@v2
+        with:
+          args: --offline --no-progress --exclude-path node_modules './**/*.md'

AGENTS.md

@@ -2,8 +2,17 @@
 
 ## Local checks
 
-- Backend: `cd apps/backend && docker compose up -d db && docker compose run --rm -v "$PWD:/workspace" backend sh -lc 'cd /workspace && HOME=/tmp pip install -r requirements-dev.txt && HOME=/tmp python -m pytest'`
-- Web: `cd apps/web && npm run lint && npm run build`
+- Everything CI runs: `make check`. `make` lists the other commands.
+- Backend only: `make test` (runs pytest in the API image against the compose database).
+- Web only: `make lint` (lint and production build).
+
+## Docs
+
+- Start at `docs/README.md`. `docs/architecture.md` says where each part of the system lives.
+- A change to how something works updates the page that describes it, in the same pull request.
+- Docs name the constant or file that holds a value; they do not copy the value.
+- `docs/decisions/` records are never edited. A changed decision gets a new record.
+- `docs/internal/` is gitignored and never committed.
 
 ## Content rules
 

CONTRIBUTING.md

@@ -1,7 +1,9 @@
 # Contributing
 
-Pull requests are welcome. `README.md` explains how to run the app locally and
-which checks CI runs; run those before opening a pull request.
+Pull requests are welcome. [docs/development.md](docs/development.md) explains
+how to run the app locally and make common changes. Run `make check`, which is
+what CI runs, before opening a pull request. For anything larger than a small
+fix, open an issue first so we can agree on the approach.
 
 ## Adding a problem
 
@@ -125,7 +127,7 @@ in your migration, hidden ones included. It fails if:
 
 ### 5. Check it
 
-Run the backend checks from `README.md`. To see the problem in the app,
+Run `make test`. To see the problem in the app,
 restart the API so the migration runs:
 
 ```bash

Makefile

@@ -0,0 +1,40 @@
+# Everyday commands. `make` alone lists them.
+BACKEND := apps/backend
+WEB := apps/web
+COMPOSE := docker compose -f $(BACKEND)/docker-compose.yml
+
+.DEFAULT_GOAL := help
+.PHONY: help setup up down logs web test lint check smoke
+
+help: ## List the commands
+	@grep -E '^[a-z]+:.*## ' $(MAKEFILE_LIST) | awk -F ':.*## ' '{ printf "  make %-7s %s\n", $$1, $$2 }'
+
+setup: ## Copy the env templates and install web dependencies
+	@test -f $(BACKEND)/.env || cp $(BACKEND)/.env.example $(BACKEND)/.env
+	@test -f $(WEB)/.env || cp $(WEB)/.env.example $(WEB)/.env
+	cd $(WEB) && npm install
+	@echo "Now fill in DB_PASSWORD and the Clerk keys in $(BACKEND)/.env and $(WEB)/.env"
+
+up: ## Start Postgres, the API and the runner
+	$(COMPOSE) up -d --build
+
+down: ## Stop them
+	$(COMPOSE) down
+
+logs: ## Follow the API and runner logs
+	$(COMPOSE) logs -f backend runner
+
+web: ## Run the web app at http://localhost:5173
+	cd $(WEB) && npm run dev
+
+test: ## Backend tests, in the API image against the compose database
+	$(COMPOSE) up -d db
+	$(COMPOSE) run --rm -v "$(CURDIR)/$(BACKEND):/workspace" backend sh -lc 'cd /workspace && HOME=/tmp pip install -q -r requirements-dev.txt && HOME=/tmp python -m pytest'
+
+lint: ## Web lint and production build
+	cd $(WEB) && npm run lint && npm run build
+
+check: test lint ## Everything CI runs
+
+smoke: ## Check a deployment: make smoke [SITE=...] [API=...]
+	./infra/smoke.sh $(or $(SITE),https://tandemcode.space) $(or $(API),https://api.tandemcode.space)