Update docs

Author: bcb

docs/gettingstarted.md

@@ -11,7 +11,9 @@ cd myapp
 ```
 
 <details>
-<summary>Click here to see how to change this clone to point "origin" to your own hosted repository (Recommended)</summary>
+<summary>
+  Recommended: Change the clone to point to your own hosted repository.
+</summary>
 
 Rename "origin" to "upstream":
 
@@ -33,11 +35,6 @@ git remote add origin https://github.com/yourname/myapp
 
 Now you can pull/push to your own repo as normal:
 
-```sh
-git pull
-git push origin head
-```
-
 <h3>Why not just fork SuperStack?</h3>
 
 Because you can't make a fork private.
@@ -56,8 +53,8 @@ Copy the example file:
 cp example.env .env
 ```
 
-> ⚠️ The .env file is for local development only. For remote deployments,
-> set environment variables using CI/CD or inline in the `docker compose up` command (be sure to avoid saving secrets in shell history).
+> ⚠️ The `.env` file is for local development only, don't write secrets to a
+> file on other environments.
 
 ## 3. Start the Stack
 
@@ -67,19 +64,20 @@ docker compose up -d
 
 That's it – your backend is live.
 
-You can now open [localhost:8000/openapi/](http://localhost:8000/openapi/)
-to explore your API.
+You can now open
+[http://localhost:8000/openapi/](http://localhost:8000/openapi/) to explore
+your API.
 
 ---
 
 ## 🧩 What Just Happened?
 
 SuperStack automatically:
 
-- Starts a fresh **Postgres** database
-- Applies initial **migrations**
-- Launches **PostgREST** and **Swagger UI**
-- Serves everything through **Caddy**
+1. Starts a fresh Postgres database
+2. Applies initial migrations
+3. Launches PostgREST and Swagger UI
+4. Serves everything through Caddy
 
 ```mermaid
 flowchart TD
@@ -90,12 +88,31 @@ flowchart TD
 
 > 💡 Only Caddy exposes a port – all services are routed through it.
 
-## Nuke everything
+## 🔄 Resetting
 
-To wipe your stack and start clean:
+If you want to start fresh:
 
 ```sh
 docker compose down --volumes
+docker compose up -d
+```
+
+This will wipe your database and re-run all migrations from scratch.
+
+## Project Structure
+
+```
+📁 bin/                  → Helper scripts (e.g. wrappers for CLI tools)
+📁 caddy/                → Custom Caddy configuration and certificates
+📁 docs/                 → Markdown files for SuperStack documentation
+📁 postgres/             → SQL migrations and configuration of the postgres container
+📄 compose.yaml          → Main Docker Compose config
+📄 compose.override.yaml → Optional local overrides (development only)
+📄 example.env           → Example environment variables — copy to `.env`
+📄 LICENSE               → License file (MIT)
+📄 logo.png              → SuperStack logo for README/docs
+📄 mkdocs.yml            → MkDocs configuration for documentation site
+📄 README.md             → Overview and quick start for the repository
 ```
 
 ## ➕ What's Next?

docs/migrations.md

@@ -1,11 +1,10 @@
 # 📜 Migrations
 
-SuperStack includes a simple built-in system for managing database schema
-migrations.
+SuperStack includes a simple system for managing database schema changes.
 
 ## ✍️ Writing Migrations
 
-Place your migration scripts in:
+Place SQL scripts in:
 
 ```
 postgres/migrations/
@@ -14,9 +13,9 @@ postgres/migrations/
 Each file should be:
 
 - A `.sql` file
-- Numbered in order (e.g. `00-init.sql`, `01-extensions.sql`, `02-auth.sql`)
+- Numbered in order (e.g. `00-init.sql`, `01-extensions.sql`, `02-create_auth_schema.sql`)
 - Written in plain SQL
-- But can include environment variables.
+- But can include environment variables
 
 ## ▶️ Applying Migrations
 
@@ -41,22 +40,10 @@ Already-applied scripts are skipped on subsequent runs.
 
 > 💡 `bin/postgres` is short for `docker compose exec postgres`
 
-## 🔄 Resetting
-
-If you want to start fresh:
-
-```sh
-docker compose down --volumes
-docker compose up -d
-```
-
-This will wipe your database and re-run all migrations from scratch.
-
 ## 🔁 Transactions
 
-Use `BEGIN;` and `COMMIT;` to wrap migration files when all included
-statements are transactional. This ensures that all changes are applied
-atomically.
+Use `BEGIN;` and `COMMIT;` to wrap migration files when all included statements
+are transactional. This ensures that all changes are applied atomically.
 
 For example:
 
@@ -78,11 +65,10 @@ create table movie (
 commit;
 ```
 
-> 💡 If your migration script only contains one statement, there's no need
-> to use a transaction, the statement will be auto-committed.
+> 💡 Statements outside of begin/commit are auto-committed.
 
-Avoid wrapping non-transactional operations in a transaction — these will
-cause errors if used inside `BEGIN ... COMMIT`.
+Avoid wrapping non-transactional operations in a transaction — these will cause
+errors if used inside `BEGIN ... COMMIT`.
 
 Examples of non-transactional statements include:
 

mkdocs.yml

@@ -44,11 +44,12 @@ markdown_extensions:
 nav:
   - Home: index.md
   - Getting Started: gettingstarted.md
-  - Build your App:
+  - Working with the Stack:
+      - Psql: psql.md
       - Migrations: migrations.md
       - Postgres Extensions: extensions.md
       - Authentication: authentication.md
       - RabbitMQ: rabbitmq.md
-  - Psql: psql.md
-  - Deploying to Remote Environments: deploying.md
-  - Upgrading SuperStack: upgrading.md
+  - Operations:
+      - Deploying SuperStack: deploying.md
+      - Upgrading SuperStack: upgrading.md