docs: prepare documentation for public open-source use

CHANGELOG.md

@@ -1,26 +1,40 @@
 # Changelog
 
-User-visible changes are recorded here. Versions correspond to
-[GitHub releases](https://github.com/0then0/form-forge/releases); detailed upgrade
-instructions accompany each release. Unreleased changes are not part of the latest
-tagged source archive.
+All notable user-visible changes are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versions match
+[GitHub releases](https://github.com/0then0/form-forge/releases), where each
+release also includes detailed upgrade instructions.
 
 ## [Unreleased]
 
 ### Added
 
-- Manual GitHub Actions workflow for Neon migrations with a separate database
-  secret, and a separate manual Netlify production build trigger.
-- Repository contribution and security policies, community templates, editor
-  settings and Git file handling conventions.
+- Manually started GitHub Actions workflows for Neon database migrations and
+  Netlify production deploys.
+- Contribution guide, security policy, code of conduct, issue and pull request
+  templates, and a releasing guide for maintainers.
+
+### Changed
+
+- Docker images and the Netlify build use Node.js 24.22.0. The pinned pnpm
+  version is 12.17.0.
+- Dependencies updated, including Next.js 16.4.5 and the Sentry SDK.
+- Documentation rewritten for new users and operators.
 
 ### Fixed
 
-- Migration command handles transport errors, limits connection and SQL waits,
-  closes connections and reports errors without printing SQL or credentials.
-  It preserves existing Drizzle migrations and history and does not retry
-  automatically. Remote migration execution can bypass a failing local network
-  path; the cause of local Neon `ETIMEDOUT` failures remains unconfirmed.
+- `pnpm db:migrate` closes its connection on network errors, limits connection,
+  lock and statement waits, and reports failures without printing SQL or
+  credentials. It does not retry automatically and keeps the existing migration
+  history.
+
+### Security
+
+- Removed vulnerable transitive versions of glob, minimatch and esbuild
+  ([GHSA-3g3m-2fjr-6pw4](https://github.com/advisories/GHSA-3g3m-2fjr-6pw4),
+  [GHSA-g3hv-75wg-m249](https://github.com/advisories/GHSA-g3hv-75wg-m249),
+  [GHSA-67mh-4wv8-2f99](https://github.com/advisories/GHSA-67mh-4wv8-2f99)).
+  None of the affected code paths were reachable in production.
 
 ## [0.2.0] - 2026-10-18
 

CONTRIBUTING.md

@@ -1,51 +1,57 @@
 # Contributing to Form Forge
 
-Form Forge is a small libre/self-hosted application. Keep changes focused and
-prefer existing services, workspace packages and platform APIs over new dependencies
-or external infrastructure. Discuss substantial features, dependencies and public
-contract changes in an issue before implementing them.
-
-By participating, follow the [Code of conduct](CODE_OF_CONDUCT.md). Report
-vulnerabilities through the [security policy](SECURITY.md), not a public bug report.
-
-## Local setup
-
-Follow [Getting started](docs/getting-started.md) for Node.js, the pinned pnpm
-version, PostgreSQL, environment variables and OAuth configuration. Use pnpm and
-commit intentional manifest changes together with `pnpm-lock.yaml`. Do not commit
-credentials, local environment files, database dumps or submission data. Environment
-examples must contain placeholders only.
-
-The [development guide](docs/development.md) describes commands, CI and test
-databases. `.editorconfig`, Biome and Prettier define formatting. Use `pnpm format`
-on your own changes; avoid unrelated formatting or snapshot updates.
-
-## Changes and pull requests
-
-- Search existing issues and PRs before opening a duplicate. Include a minimal
-  reproduction for bugs and the user problem for feature requests.
-- Work on a branch in your fork and open a focused PR against `main`. Explain
-  behavior before and after, compatibility implications and checks actually run.
-  Add screenshots for meaningful UI changes, with personal data removed.
-- Add regression tests for meaningful behavior. Preserve server-side workspace
-  authorization, immutable published schemas and answers, idempotency, transactional
-  outbox semantics and compatibility with existing forms.
-- Generate additive migrations with `pnpm db:generate`; commit SQL and Drizzle
-  metadata together. Do not edit applied migrations or reset migration history.
-  Test both empty-database installation and upgrades on disposable local databases.
-- Use Conventional Commits in English, such as `fix: preserve submission filters`.
-  No CLA is required; contributions are provided under the project's
-  [Apache License 2.0](LICENSE).
-
-The sole maintainer may push directly to `main`; external and Dependabot changes
-use PRs. This does not waive verification. Follow the
-[dependency maintenance policy](docs/dependency-maintenance.md) for toolchain,
-major and security updates. Do not merge unreviewed dependency changes just to
-clear the update queue.
-
-## Verification
-
-Run checks relevant to the change and report any checks you could not run:
+Thank you for your interest in Form Forge. Bug reports, documentation fixes and
+focused improvements are all welcome.
+
+Form Forge is a small self-hosted application, so we prefer existing services,
+workspace packages and platform APIs over new dependencies or external
+infrastructure. Please open an issue to discuss substantial features, new
+dependencies or changes to public contracts before you start working on them.
+
+By participating, you agree to follow the [Code of conduct](CODE_OF_CONDUCT.md).
+Report vulnerabilities through the [security policy](SECURITY.md), not in a public
+issue.
+
+## Set up your environment
+
+Follow [Getting started](docs/getting-started.md) to install Node.js and pnpm,
+start PostgreSQL, configure environment variables and GitHub sign-in. The
+[development guide](docs/development.md) describes the available commands, tests
+and CI.
+
+- Use pnpm, and commit intended manifest changes together with `pnpm-lock.yaml`.
+- Never commit credentials, local environment files, database dumps or response
+  data. Example environment files contain placeholders only.
+- `.editorconfig`, Biome and Prettier define formatting. Run `pnpm format` on
+  your changes and avoid unrelated formatting changes.
+
+## Make a change
+
+- Search existing issues and pull requests first. For bugs, include a minimal
+  reproduction; for features, describe the problem you want to solve.
+- Work on a branch in your fork and open a focused pull request against `main`.
+  Describe the behavior before and after, compatibility implications and the
+  checks you ran. Add screenshots for visible UI changes, with personal data
+  removed.
+- Add regression tests for meaningful behavior. Keep these guarantees intact:
+  server-side workspace authorization, immutable published schemas and answers,
+  idempotent submissions, the transactional outbox, and compatibility with
+  existing forms.
+- For database changes, generate a new migration with `pnpm db:generate` and
+  commit the SQL and Drizzle metadata together. Never edit an applied migration
+  or reset migration history. Test both a fresh installation and an upgrade on
+  disposable local databases.
+- Write commit messages in English using
+  [Conventional Commits](https://www.conventionalcommits.org/), for example
+  `fix: preserve submission filters`.
+
+All changes to `main`, including the maintainer's, go through pull requests with
+passing CI. Dependency updates follow the
+[dependency maintenance policy](docs/dependency-maintenance.md).
+
+## Verify your change
+
+Run the checks relevant to your change and mention any you could not run:
 
 ```sh
 pnpm format:check
@@ -56,30 +62,31 @@ pnpm test
 pnpm test:deployment
 ```
 
-For runtime, database or UI changes, also run the applicable PostgreSQL,
+For changes to runtime behavior, the database or the UI, also run the PostgreSQL,
 Playwright and build checks from [Development](docs/development.md) and
-[Deployment verification](deploy/VERIFICATION.md). `pnpm test` skips PostgreSQL
-integration tests unless `TEST_DATABASE_URL` is set. Integration and browser
-suites delete fixture data: use separate disposable local databases, never a
-shared or production database. A successful build alone does not verify a change.
-
-## Automation and releases
-
-The existing [workflows](.github/workflows) have distinct responsibilities:
-
-- **CI** runs on PRs and pushes to `main`, using disposable PostgreSQL and test
-  credentials. It checks formatting, types, lint, unused code, tests and builds.
-- **Monthly dependency review** opens a review issue; Dependabot opens update PRs.
-  Neither automatically merges changes.
-- **Database migrations** runs manually from `main`, using the dedicated Neon
-  secret. See the [Neon migration guide](deploy/NETLIFY.md). It never runs on push.
-- **Deploy production** is a separate manual Netlify build trigger. Success means
-  Netlify accepted the request, not that deployment finished.
-- **Release** publishes committed source and checksums when a `v*` tag is pushed
-  and matches `deploy/VERSION`. A release does not require a PR and does not
-  deploy the application or migrate its database.
-
-Maintainers update [CHANGELOG.md](CHANGELOG.md), `deploy/VERSION` and
-`deploy/RELEASE_NOTES.md` for a release after checking the intended revision.
-Detailed release notes must describe migrations and downgrade limits. Do not
-create tags or run production workflows as part of an ordinary contribution.
+[Deployment verification](deploy/VERIFICATION.md). `pnpm test` skips the
+PostgreSQL integration tests unless `TEST_DATABASE_URL` is set. Integration and
+browser tests delete their data, so use separate disposable local databases and
+never a shared or production database. A successful build alone does not verify a
+change.
+
+## Automation
+
+The [GitHub Actions workflows](.github/workflows) are:
+
+- **CI:** runs on every pull request and push to `main` with a disposable
+  PostgreSQL database and test credentials. It checks formatting, types, lint and
+  unused code, runs all test suites and builds the application.
+- **Dependency review:** opens a monthly issue listing major and toolchain
+  updates. Dependabot opens update pull requests. Neither merges anything
+  automatically.
+- **Database migrations** and **Deploy production:** started manually by the
+  maintainer for the Netlify installation.
+- **Release:** publishes a source release when a version tag is pushed.
+
+See [Releasing](docs/releasing.md) for how releases are made.
+
+## License
+
+There is no contributor license agreement. By submitting a contribution, you
+agree that it is provided under the project's [Apache License 2.0](LICENSE).

README.md

@@ -54,23 +54,33 @@ For production, use the [Docker Compose guide](deploy/README.md) or [Netlify gui
 
 ## Documentation
 
+Using Form Forge:
+
 - [Getting started](docs/getting-started.md): requirements, environment, database, OAuth and your first form.
-- [User guide](docs/user-guide.md): account linking, roles, archives, intake, privacy and response management.
-- [Public API, OpenAPI and MCP](docs/api.md): submission contracts, idempotency, quotas and authenticated integrations.
-- [Embedding](docs/embedding.md): iframe setup, automatic height, lifecycle events and cleanup.
-- [Webhooks](docs/webhooks.md): signature verification, retries, outbox delivery and recovery.
-- [Architecture](docs/architecture.md): workspace packages, data model and project scope.
-- [Development](docs/development.md): commands, CI, database tests and Playwright.
-- [Dependency maintenance](docs/dependency-maintenance.md): Dependabot schedules, security fixes and monthly reviews.
-- [Deployment and operations](docs/operations.md): production configuration, upgrades, backups and monitoring.
+- [User guide](docs/user-guide.md): forms, sign-in methods, intake controls, privacy, responses and roles.
+- [Public API, OpenAPI and MCP](docs/api.md): submission contract, idempotency, limits and integrations.
+- [Embedding](docs/embedding.md): iframe setup, automatic height and events.
+- [Webhooks](docs/webhooks.md): payload format, signature verification, retries and deduplication.
 
-## Contributing
+Running an installation:
+
+- [Deployment and operations](docs/operations.md): configuration, reverse proxy, upgrades, backups and monitoring.
+- [Docker Compose](deploy/README.md): single-host installation, backup and restore.
+- [Netlify](deploy/NETLIFY.md): Netlify with Neon and Inngest Cloud.
+- [Deployment verification](deploy/VERIFICATION.md): automated checks and what they prove.
 
-Read [CONTRIBUTING.md](CONTRIBUTING.md) for setup, verification and pull request guidance, and follow the [Code of conduct](CODE_OF_CONDUCT.md). Integration and browser tests require disposable databases and remove test data.
+Working on the project:
+
+- [Architecture](docs/architecture.md): repository layout, technology and data flow.
+- [Development](docs/development.md): commands, tests, CI and Playwright.
+- [Dependency maintenance](docs/dependency-maintenance.md): Dependabot, security updates and toolchain changes.
+- [Releasing](docs/releasing.md): versioning and the release workflow.
+
+## Contributing
 
-Report bugs and discuss changes through [GitHub Issues](https://github.com/0then0/form-forge/issues).
+Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for setup, checks and pull request guidance, and follow the [Code of conduct](CODE_OF_CONDUCT.md).
 
-For vulnerabilities, follow [SECURITY.md](SECURITY.md) instead of posting details publicly. See [CHANGELOG.md](CHANGELOG.md) for release history and unreleased changes.
+Report bugs and suggest features through [GitHub Issues](https://github.com/0then0/form-forge/issues). To report a vulnerability, follow [SECURITY.md](SECURITY.md) instead of opening a public issue. See [CHANGELOG.md](CHANGELOG.md) for release history.
 
 ## License
 

SECURITY.md

@@ -2,37 +2,43 @@
 
 ## Supported versions
 
-Security fixes target the latest stable release. Older releases and prereleases
-do not have a separate maintenance commitment; upgrade to the latest stable
-version when a fix is available. See [releases](https://github.com/0then0/form-forge/releases)
-and [CHANGELOG.md](CHANGELOG.md). There is no guaranteed response or fix timeline.
-
-## Report a vulnerability privately
-
-Do not disclose exploitable vulnerabilities, credentials or submission data in
-public issues, PRs or discussions.
-
-Use **Security → Advisories → Report a vulnerability** on
-[GitHub](https://github.com/0then0/form-forge/security/advisories/new) when private
-vulnerability reporting is enabled. If that option is unavailable, contact
-[the maintainer](https://github.com/0then0) through an available private contact
-method. If no private contact is listed, open a minimal issue requesting a private
-security contact, without describing the vulnerability or sharing a proof of concept.
-Private reporting must be enabled in GitHub repository settings; this file alone
-does not enable it.
-
-Include the affected version or commit, deployment type, prerequisites, expected
-and observed behavior, impact and a minimal reproduction using synthetic data.
-Avoid live credentials and real responses. Test only installations you own or
-have permission to assess. Coordinate public disclosure after maintainers have
-assessed the report and users have a fix or mitigation.
-
-## Operating an installation
-
-Deployment owners are responsible for access control, TLS, secrets, backups,
-dependency updates and monitoring. Follow the [operations guide](docs/operations.md)
-and the [dependency maintenance policy](docs/dependency-maintenance.md).
-Dependabot alerts and security updates require separate repository settings.
-Rotate exposed credentials at their source; removing them from a commit is not
-enough. Report an incident involving your own stored data to your installation's
-operator, and report a reproducible software vulnerability to the project.
+Security fixes are made for the latest stable release. Older releases and
+prereleases are not maintained separately; upgrade to the latest stable version
+when a fix is available. See the
+[releases](https://github.com/0then0/form-forge/releases) and
+[CHANGELOG.md](CHANGELOG.md).
+
+There is no guaranteed response or fix time.
+
+## Reporting a vulnerability
+
+Please do not disclose vulnerabilities, credentials or response data in public
+issues, pull requests or discussions.
+
+Report vulnerabilities privately through
+[GitHub Security Advisories](https://github.com/0then0/form-forge/security/advisories/new)
+(**Security → Advisories → Report a vulnerability**). If that option is not
+available, contact [the maintainer](https://github.com/0then0) through a private
+contact method listed on their profile. If you cannot find one, open an issue
+asking for a private security contact, without describing the vulnerability.
+
+Please include:
+
+- the affected version or commit and deployment type;
+- prerequisites, expected and observed behavior, and impact;
+- a minimal reproduction using synthetic data.
+
+Do not use live credentials or real responses. Test only installations you own or
+have permission to test. We will coordinate public disclosure with you once the
+report has been assessed and a fix or mitigation is available.
+
+## Running an installation
+
+Operators are responsible for access control, TLS, secrets, backups, dependency
+updates and monitoring of their installation. Follow the
+[operations guide](docs/operations.md). If a credential is exposed, rotate it at
+its source; removing it from a commit is not enough.
+
+Report incidents involving data stored in a particular installation to that
+installation's operator. Report reproducible vulnerabilities in the software to
+this project.

apps/web/e2e/form-lifecycle.spec.ts

@@ -202,7 +202,7 @@ test("creates, publishes, submits, fails, retries, and succeeds", async ({
   });
   await expect(page.getByRole("status")).toBeVisible();
 
-  // The new after() path must finish its failed ingestion attempt before the
+  // The after() path must finish its failed ingestion attempt before the
   // fixture advances persisted scheduling and takes over as the test scheduler.
   await expect
     .poll(

apps/web/src/lib/openapi.ts

@@ -111,7 +111,7 @@ export const openApiDocument = {
     title: "Form Forge product API",
     version: "1.0.0",
     description:
-      "Public submissions and workspace product operations. Admin access uses the existing NextAuth session; owner/editor/viewer permissions are enforced by each service. OAuth callbacks, scheduler and internal test controls are outside this document. MCP transport is documented separately in README.",
+      "Public submissions and workspace product operations. Admin access uses the NextAuth session; owner/editor/viewer permissions are enforced by each service. OAuth callbacks, scheduler and internal test controls are outside this document. The MCP endpoint is documented in docs/api.md.",
   },
   servers: [{ url: "/" }],
   components: {