# Structure & conventions

This repo hosts multiple learning topics. Each topic is an independent **teaching
workspace** (the `/teach` model: *one mission per workspace*), and all topics
share a single look via root-level assets.

## Layout

```
technotes/
├── index.html              # site landing — lists every topic
├── assets/                 # SHARED across all topics
│   ├── styles.css          #   one stylesheet → one consistent course look
│   └── quiz.js             #   reusable retrieval-practice widget
├── elasticsearch/          # a topic = a full teaching workspace
│   ├── index.html          #   topic landing (lessons + reference index)
│   ├── MISSION.md          #   why this topic is being learned
│   ├── RESOURCES.md        #   curated high-trust sources
│   ├── NOTES.md            #   teaching scratchpad / learner preferences
│   ├── lessons/            #   NNNN-slug.html — the units of teaching
│   ├── reference/          #   glossary + cheat sheets (revisited often)
│   └── learning-records/   #   NNNN-slug.md — decision-grade insights
├── redis/                  # (future topic, same shape)
├── mysql/                  # (future topic, same shape)
├── README.md
└── STRUCTURE.md
```

## Path conventions (important)

Assets are shared at the repo root, so relative links depend on depth:

| From | Link to assets |
|------|----------------|
| `<topic>/index.html`            | `../assets/styles.css` |
| `<topic>/lessons/NNNN.html`     | `../../assets/styles.css` |
| `<topic>/reference/NAME.html`   | `../../assets/styles.css` |

Within a topic, cross-links stay relative to the topic (e.g. a lesson links a
reference as `../reference/NAME.html`).

## Adding a new topic

1. `mkdir <topic>` and create the workspace files: `MISSION.md`, `RESOURCES.md`,
   `NOTES.md`, and the `lessons/`, `reference/`, `learning-records/` dirs.
2. Reuse the shared `assets/` — **do not** copy `styles.css`/`quiz.js` into the
   topic. Link them with the depth-correct path above.
3. Add a `<topic>/index.html` landing page (copy Elasticsearch's as a template).
4. Add a card for the topic in the root `index.html`.

> Running `/teach <topic>` from inside `technotes/`? Point it at the topic
> subfolder as its workspace, and tell it shared components live at `../assets`
> (referenced as `../../assets` from `lessons/` and `reference/`).

## Deployment — Cloudflare Pages (Git integration)

Static site, **no build step**. Deployed by connecting the GitHub repo in the
Cloudflare dashboard; every push to `main` auto-redeploys.

Project settings (Pages → Settings → Builds & deployments):

- **Framework preset:** None
- **Build command:** *(empty)*
- **Build output directory:** `/`
- **Deploy command:** *(empty — do NOT set `wrangler deploy`; this is a static
  Pages site, not a Worker)*

> Do **not** keep a `wrangler.toml` in the repo. The Cloudflare build image
> detects it and tries to run `wrangler deploy` (a Workers command), which fails
> with *“run `wrangler pages deploy` instead.”* This repo is served as plain
> static files — no wrangler needed.

`.assetsignore` keeps tooling files (`.git`, `node_modules`, `package.json`, …)
out of the uploaded site.

To keep the live site private (the repo is private, but a Pages URL is public by
default), put it behind **Cloudflare Access**: Zero Trust → Access → add an
application over the Pages domain, allow only your email.