Docs
Local framework notes for JoLo apps. These pages are stubs, not an upstream manual. Index: docs/vendor-framework-docs/SOURCE.md.
Actions
docs/vendor-framework-docs/actions.md
# Actions
Status: stub
JoLo apps expose shared operations as actions so the product UI and an automated agent call the same code. An action has a stable name, a JSON input, a clear read or write effect, and a result the caller can check.
## Naming
Use `verb-resource` names: `list-projects`, `update-project`, `archive-project`. Reads must be safe to retry. Writes must say what changed.
## Rules
- Put product behavior in actions. Add a custom HTTP route only when the protocol cannot be JSON: file upload, a stream, a webhook, or an OAuth redirect.
- Do not pass secrets, session cookies, or raw credentials as action arguments. The server reads those from the environment.
- Keep large bytes out of action payloads and out of SQL. Pass a storage URL or an id.
- After a write, read the record back before telling a user it succeeded.
- Do not invent fields the action did not return. If the call failed, say it failed.
## Shape
A read looks like this at the boundary, independent of any helper name:
```json
{ "name": "list-projects", "input": { "limit": 20 } }
```
The matching result lists records the caller is allowed to see, not every row in the table.
## This repository
The docs site does not ship sample actions. Add them in the app repository. If an export name or import path is required to declare an action, record it in `docs/runtime-contracts.md` instead of copying it into app docs.
Authentication
docs/vendor-framework-docs/authentication.md
# Authentication Status: stub JoLo apps authenticate people with server-side sessions. The docs site at `framework.gojolo.io` is public documentation plus a static operator index. It does not sign users in. ## Rules for apps - Generate the auth secret outside the repo. Store it in the host environment or the deploy system. Never commit it, paste it into docs, or print it in logs. - Set the public site URL in production. Do not trust the incoming `Host` header for redirects or cookie scope. - Limit trusted origins to the real app origins. - A signed-in user is not an operator. Admin capabilities are a separate, explicit grant. - Session cookies in production are `HttpOnly` and `Secure`. ## Docs site `/admin` on this site lists commands and the environment example. It is not an authenticated console. Do not put customer data, tokens, or live environment values on it. The variable names the runtime reads for sessions are listed in `docs/runtime-contracts.md`. App docs can say "auth secret" and "public site URL" without repeating vendor names. ## Local development A missing auth secret is expected in this repository. Do not invent one to make `pnpm run doctor` pass. Doctor does not log in.
Storage
docs/vendor-framework-docs/storage.md
# Storage Status: stub Structured app data belongs in SQL. File bytes belong in object storage. The docs site stores neither: its pages are files in this repository. ## Rules for apps - Local development may use a local SQL directory. Production uses a hosted database URL from the environment. - Do not store video, audio, images, PDFs, or base64 blobs in SQL rows, settings, or application state. Store a URL or an id, and keep the bytes in the configured bucket. - Bucket names, access keys, and endpoints come from the environment. Examples use empty placeholders. - Do not point a new app at another app's production database or bucket. - Do not commit a dump, a sqlite file with customer rows, or a `.env` that contains a connection string. ## This repository `pnpm run doctor` does not connect to a database. A missing database URL is the correct state here. Adding one is not required to serve `/health`. If a future change makes this site persist anything, document the new variable in `docs/runtime-contracts.md` and keep the value out of git.
Deployment
docs/vendor-framework-docs/deployment.md
# Deployment Status: stub JoLo apps deploy as a Node process behind the existing host reverse proxy. This repository's docs site is the reference shape: build in the pipeline, transfer artifacts, write environment on the server, restart a service, then request `/health`. ## Pipeline The draft pipeline is the repo-root `buddy.yml`. It is not live until the checklist in `docs/FINAL_STEPS.md` is done. Site user, path, port, and public URL are pipeline variables. They are not committed. Do not bake credentials into the image or the transferred tree. The SSH step writes `.env` on the host with mode `600`. ## Release checks Before a production run: 1. `pnpm run typecheck` 2. `pnpm run build` 3. `pnpm run doctor` 4. `pnpm run docs:check` 5. `pnpm run brand:check` `doctor` already runs the last two. The list is repeated so a pipeline can show each gate. ## Health Production is ready when `GET /health` returns `"ok": true`. Do not treat the HTML home page as the only check. A failed unit should leave the previous process only if the pipeline is written that way; this draft restarts the unit and then curls the new port, and it fails the run if that curl does not succeed. Site-specific steps for `framework.gojolo.io` are in `docs/deployment.md`.
Security
docs/vendor-framework-docs/security.md
# Security Status: stub ## Secrets Scripts in this repo must not fetch, print, or invent secrets. `.env.example` contains names and comments only. Real values stay in a local `.env` (gitignored) or in the deploy system's variables. If a command would need a token to succeed, stop and ask. Do not search the machine for credential files to unblock a docs change. ## Brand boundary User-facing docs and the docs site must not name the upstream runtime vendor. The only exception is `docs/runtime-contracts.md`, which records the package pin on purpose. `pnpm run brand:check` enforces that split. A lockfile match is not permission to mention the vendor in README or on `/docs`. ## Dependencies Keep the runtime dependency on the exact version recorded in the exception file and in `package.json`. Do not add product-template trees from that package. Review a version bump in the same change as `docs/runtime-contracts.md`. ## Docs site The server reads a fixed list of repository files and returns HTML or `/health`. It does not proxy arbitrary URLs, does not render unescaped file text, and does not echo environment values. Unknown paths return 404. Methods other than `GET` and `HEAD` return 405. Do not add a query parameter that selects a file path. ## Reporting Do not commit exploit details or customer data into this repo. Describe a fix by its behavior change, without pasting secrets into the commit message.