@terreno/mcp 57.3.0 → 57.4.0

package/src/docs/versioned/next/tasks/org-management-ui.md

@@ -6,19 +6,19 @@ Supporting skills (all tasks): `update-docs`. Models: `mongoose-schema-safety`.
 
 ## Phase 1 — Models + context
 
-- [ ] **Task 1.1**: Organization + Membership models
+- [x] **Task 1.1**: Organization + Membership models
   - Delivers: persist orgs and per-org `roleName` (`org-admin` \| `member`)
   - Files: `api/src/orgs/organizationModel.ts`, types, `api/src/orgs/*.test.ts`
   - Blocked by: none
   - Docs: field `description`s (OpenAPI); note in `docs/reference/api.md` stub section if the page is updated later in 6.1
   - Acceptance: unit tests for compound unique index and duplicate membership rejection
-- [ ] **Task 1.2**: `orgScopedPlugin`
+- [x] **Task 1.2**: `orgScopedPlugin`
   - Delivers: required indexed `organizationId` on consumer schemas
   - Files: `api/src/orgs/orgPlugin.ts` + tests
   - Blocked by: 1.1
   - Docs: none until 6.1
   - Acceptance: save without org fails; index present
-- [ ] **Task 1.3**: Org context middleware + `OrgQueryFilter`
+- [x] **Task 1.3**: Org context middleware + `OrgQueryFilter`
   - Delivers: Q13 header matrix; lists never cross orgs
   - Files: `api/src/orgs/orgContext.ts`, `orgPermissions.ts`, `api/src/permissions.ts` (stop using `User.organizationIds`)
   - Blocked by: 1.1, 1.2
@@ -27,7 +27,7 @@ Supporting skills (all tasks): `update-docs`. Models: `mongoose-schema-safety`.
 
 ## Phase 2 — RBAC
 
-- [ ] **Task 2.1**: `organization` statements + `operator` role + membership-scoped `org-admin`
+- [x] **Task 2.1**: `organization` statements + `operator` role + membership-scoped `org-admin`
   - Delivers: platform vs org grants as in the IP tables
   - Files: `api/src/rbac/statements.ts`, `roleModel.ts`, resolve/can path for Membership `roleName`, tests
   - Blocked by: 1.3
@@ -36,13 +36,13 @@ Supporting skills (all tasks): `update-docs`. Models: `mongoose-schema-safety`.
 
 ## Phase 3 — OrgsApp routes
 
-- [ ] **Task 3.1**: Operator org CRUD + `/orgs/mine`
+- [x] **Task 3.1**: Operator org CRUD + `/orgs/mine`
   - Delivers: create/list-all/mine/read/patch/soft-delete + `onOrgAudit`
   - Files: `api/src/orgs/orgsApp.ts`, exports, OpenAPI, supertest
   - Blocked by: 2.1
   - Docs: none until 6.1
   - Acceptance: org-admin 403 on `GET /orgs`; operator 200; create does not require membership; disable/soft-delete suspends memberships
-- [ ] **Task 3.2**: Members attach / patch / delete + last-admin guards
+- [x] **Task 3.2**: Members attach / patch / delete + last-admin guards
   - Delivers: existing-user attach; no email; last `org-admin` protected
   - Files: `api/src/orgs/orgsApp.ts` + tests
   - Blocked by: 3.1
@@ -51,7 +51,7 @@ Supporting skills (all tasks): `update-docs`. Models: `mongoose-schema-safety`.
 
 ## Phase 4 — Admin backend
 
-- [ ] **Task 4.1**: Admin org routes + AdminApp tenant context
+- [x] **Task 4.1**: Admin org routes + AdminApp tenant context
   - Delivers: admin UI can call org APIs; generic admin model lists use context filter
   - Files: `admin-backend/src/*` (org registration or aliases), AdminApp queryFilter/preCreate, tests
   - Blocked by: 3.2
@@ -60,31 +60,31 @@ Supporting skills (all tasks): `update-docs`. Models: `mongoose-schema-safety`.
 
 ## Phase 5 — Admin frontend
 
-- [ ] **Task 5.1**: `OrgDirectoryScreen` (operator)
+- [x] **Task 5.1**: `OrgDirectoryScreen` (operator)
   - Delivers: all-orgs table, create, disable, enter org
   - Files: `admin-frontend/src/orgs/OrgDirectoryScreen.tsx` + tests
   - Blocked by: 4.1
   - Docs: `docs/reference/admin-frontend.md` component section
   - Acceptance: loading/error/empty; org-admin nav hidden in unit test via role prop/fixture
-- [ ] **Task 5.2**: `OrgSwitcher` + `useOrgContext` (header + URL)
+- [x] **Task 5.2**: `OrgSwitcher` + `useOrgContext` (header + URL)
   - Delivers: Q10/Q13 client behavior for org-admins and operators-in-org
   - Files: `admin-frontend/src/orgs/OrgSwitcher.tsx`, `useOrgContext.tsx`, `AdminShellLayout` slot
   - Blocked by: 5.1
   - Docs: admin-frontend reference
   - Acceptance: switching sets `X-Organization-Id` on subsequent admin queries (test with mocked api); single-org org-admin still renders org name
-- [ ] **Task 5.3**: Org settings + members table
+- [x] **Task 5.3**: Org settings + members table
   - Delivers: settings PATCH; members DataTable; add existing user; last-admin error; disabled Invite; billing placeholder
   - Files: `admin-frontend/src/orgs/OrgSettingsScreen.tsx`, `OrgMembersScreen.tsx` + tests
   - Blocked by: 5.2, 3.2
   - Docs: admin-frontend reference
   - Acceptance: Invite control disabled; billing placeholder visible; last-admin error shown
-- [ ] **Task 5.4**: Host wiring — admin-spa + example-frontend `/admin`
+- [x] **Task 5.4**: Host wiring — admin-spa + example-frontend `/admin`
   - Delivers: routes on both hosts; SDK regen
   - Files: `admin-spa/app/orgs/*`, `example-frontend/app/admin/orgs/*`, `example-frontend/store/openApiSdk.ts` (generated)
   - Blocked by: 5.3
   - Docs: `docs/reference/admin-spa.md` nav entry
   - Acceptance: `cd example-frontend && bun run sdk` compiles; both apps have `/admin/orgs` routes
-- [ ] **Task 5.5**: Frontend verification
+- [x] **Task 5.5**: Frontend verification
   - Delivers: evidence org-admin vs operator flows
   - Files: `/opt/cursor/artifacts/` (not in repo)
   - Blocked by: 5.4, 6.2
@@ -93,13 +93,13 @@ Supporting skills (all tasks): `update-docs`. Models: `mongoose-schema-safety`.
 
 ## Phase 6 — Example + docs
 
-- [ ] **Task 6.1**: Docs (same slice as behavior; can land incrementally but must be complete before Brew)
+- [x] **Task 6.1**: Docs (same slice as behavior; can land incrementally but must be complete before Brew)
   - Delivers: stranger can operate orgs from docs
   - Files: `docs/how-to/add-organizations.md`, `docs/explanation/organizations.md`, `docs/reference/api.md`, `docs/reference/admin-backend.md`, `docs/reference/admin-frontend.md`, `docs/reference/admin-spa.md`, `.rulesync/**` if agent rules need org context
   - Blocked by: 4.1 (content must match shipped routes)
   - Docs: (this task)
   - Acceptance: `bun run website:build` (or package docs check used in CI); how-to has one minimal OrgsApp + AdminApp example
-- [ ] **Task 6.2**: example-backend migration + seeds
+- [x] **Task 6.2**: example-backend migration + seeds
   - Delivers: Membership instead of `User.organizationIds`; operator + two org-admins
   - Files: `example-backend/src/models/user.ts`, `types/models/userTypes.ts`, `api/projects.ts`, `scripts/seed-*`, `access.ts`, `rbacRoles.ts`, tests
   - Blocked by: 3.2, 2.1

package/src/docs/versioned/next/tutorials/README.md

@@ -4,4 +4,4 @@ Learning-oriented, hands-on lessons. Start here if you are new to Terreno.
 
 ## Contents
 
-- [Getting started](getting-started.md) — Install, run the examples, and see the stack in action
+- [Getting started](getting-started.md) — Scaffold a new app with `create-terreno-app`, run it locally, or explore monorepo examples

package/src/docs/versioned/next/tutorials/getting-started.md

@@ -1,44 +1,84 @@
 # Getting Started
 
-Run the example full stack to see Terreno in action.
+Create a new Terreno app with the scaffolding CLI, then run it locally.
 
 ## Prerequisites
 
 - [Bun](https://bun.sh/) installed
-- MongoDB running (for the backend example)
+- MongoDB as a **replica set** (required for sync and realtime — see [deployment baseline](../explanation/deployment-baseline.md))
 
-## Steps
+## 1. Scaffold a new app
 
-1. **Clone and install**
+From an empty parent directory:
 
-   ```bash
-   bun install
-   ```
+```bash
+bunx create-terreno-app my-app --display-name "My App"
+```
 
-2. **Start the backend** (terminal 1)
+npm alternative:
 
-   ```bash
-   bun run backend:dev
-   ```
+```bash
+npm create terreno-app my-app -- --display-name "My App"
+```
 
-   Backend runs at `http://localhost:4000`. OpenAPI spec at `/openapi.json`.
+This writes `my-app/backend` and `my-app/frontend` plus deploy and agent config. The CLI does not install dependencies or seed data.
 
-3. **Start the frontend** (terminal 2)
+Full flag reference, layout, and deploy notes: [Create a Terreno app](../how-to/create-a-terreno-app.md).
 
-   ```bash
-   bun run frontend:web
-   ```
+## 2. Install dependencies
 
-   Frontend runs in the browser and talks to the backend.
+```bash
+cd my-app
+(cd backend && bun install)
+(cd frontend && bun install)
+```
 
-4. **Optional: regenerate SDK** after backend route changes
+## 3. Start MongoDB
 
-   ```bash
-   cd example-frontend && bun run sdk
-   ```
+Use Atlas or a local single-node replica set. The scaffolded `backend/.env` points at `mongodb://127.0.0.1:27017/my_app?replicaSet=rs0` (database name derived from `appName`).
+Follow [Start MongoDB (replica set)](../how-to/create-a-terreno-app.md#3-start-mongodb-replica-set) for local commands.
+
+## 4. Seed and start the backend
+
+```bash
+(cd backend && bun run seed)
+(cd backend && bun run dev)
+```
+
+Backend runs at `http://localhost:4000`. OpenAPI spec at `/openapi.json`.
+
+Seed users: `test@example.com` and `admin@example.com`, password `testpassword123`.
+
+## 5. Start the frontend
+
+Keep the backend running while generating the SDK.
+
+```bash
+(cd frontend && bun run sdk)
+(cd frontend && bun run web)
+```
+
+Frontend runs at `http://localhost:8082`. Sign in with `test@example.com` / `testpassword123`.
+
+## Explore the Terreno monorepo examples
+
+If you are contributing to Terreno or want reference implementations inside this repository:
+
+```bash
+git clone https://github.com/FlourishHealth/terreno.git
+cd terreno && bun run bootstrap
+```
+
+| Service | Port | Command (from repo root) |
+| --- | --- | --- |
+| example-backend | 4000 | `bun run backend:dev` |
+| example-frontend web | 8082 | `EXPO_PUBLIC_API_URL=http://localhost:4000 bun run frontend:web` |
+
+The example backend needs `MONGO_URI` (replica set) and auth secrets — see the repository [AGENTS.md](https://github.com/FlourishHealth/terreno/blob/master/AGENTS.md) (Cursor Cloud section). Seed with `bun run backend:seed` from the repo root.
 
 ## Next steps
 
-- [How to create a model](../how-to/create-a-model.md) — Learn model conventions including required field descriptions
+- [Create a Terreno app](../how-to/create-a-terreno-app.md) — CLI flags, layout, deploy, MCP write path
+- [How to create a model](../how-to/create-a-model.md) — Model conventions including required field descriptions
 - [How-to guides](../how-to/) — Task-focused guides
 - [Reference](../reference/) — Package and API details