Feat files

.dockerignore

@@ -0,0 +1,6 @@
+**/node_modules/
+**/dist/
+**/.turbo/
+**/coverage/
+**/*.log
+.git/

.github/instructions/general.instructions.md

@@ -15,6 +15,15 @@ When defining functions, use an object for arguments instead of individual param
 
 Prefer using functions instead of classes for better simplicity and composability.
 
+## Naming Conventions
+
+- User kebab-case for folder names (e.g., `my-folder`).
+- Use camelCase for file names (e.g., `myFile.ts`).
+- Use camelCase for variable and function names (e.g., `myVariable`, `myFunction`).
+- Use PascalCase for type and interface names (e.g., `MyType`, `MyInterface`).
+- Use uppercase with underscores for constants (e.g., `MY_CONSTANT`).
+- For test files, use the same name as the file being tested with `.test` appended before the extension (e.g., `myFile.test.ts`).
+
 ## Linting
 
 To fix ESLint issues in a specific file, run `pnpm eslint --fix path/to/file`.
@@ -25,4 +34,20 @@ If you need to change the database schema, read the instructions in `packages/po
 
 ## Documentation
 
-All documentation must be written in English.
+All documentation must be written in English. The target audience is developers with technical skills — write concisely and precisely, assume familiarity with REST APIs, JWT, and common backend concepts, and prefer code examples over prose descriptions.
+
+## Implementation Checklist
+
+Every implementation — whether adding a new feature or changing existing behavior — must complete all of the following steps before being considered done:
+
+1. **Implement business logic** — Write or update code in `packages/server/src/lib/<module>.ts`. All database access goes here; route handlers must stay free of direct DB calls.
+
+2. **REST API** — Add or update route handlers in `packages/server/src/rest/v1/<module>.ts`. Every handler must have an `@openapi` JSDoc block and the corresponding OpenAPI spec in `packages/server/src/rest/openapi/v1/<module>.yaml` must be kept in sync.
+
+3. **Module docs** — Update the module documentation page at `packages/website/docs/modules/<module>.md`, including any changes to the data model, key concepts, or the `## Permissions` table.
+
+4. **MCP tool** (project-scoped changes only) — If the change affects a resource that is exposed through the MCP server, add or update the tool in `packages/server/src/mcp/tools/<module>.ts` and ensure it is registered in `packages/server/src/mcp/tools/index.ts`.
+
+5. **Tests** — Add or update tests in `packages/server/tests/unit/tests/<module>.test.ts`. Every new route and every changed lib function must have coverage (happy path, `401`, `403`, and relevant edge cases).
+
+6. **Smoke test** (when applicable) — If the change introduces a new user-facing flow (e.g., a new resource lifecycle), add the corresponding steps to `tests/smoke-test.sh`. Run it with `pnpm run -w smoke-test` to verify end-to-end behaviour against a live server.

.github/instructions/modules.instructions.md

@@ -0,0 +1,44 @@
+---
+applyTo: '**'
+description: Instructions for creating and maintaining modules across the codebase.
+---
+
+# Module Instructions
+
+A module is a named resource (e.g., `files`, `users`) that is exposed through the REST API, the MCP server, and documented in the website. Whenever a module is created or changed, **all four areas must be updated together**:
+
+1. **REST** — route handlers and OpenAPI spec
+2. **MCP** — tool definitions in the MCP server
+3. **Docs** — module documentation in the website
+4. **Tests** — unit tests covering the new or changed behavior
+
+## Checklist for Every Module Change
+
+- [ ] Business logic updated in `packages/server/src/lib/<module>.ts`
+- [ ] REST routes updated in `packages/server/src/rest/v1/<module>.ts` with `@openapi` JSDoc blocks
+- [ ] Module router registered in `packages/server/src/rest/v1/index.ts`
+- [ ] MCP tools updated in `packages/server/src/mcp/tools/<module>.ts`
+- [ ] Module docs updated in `packages/website/docs/modules/<module>.md`
+- [ ] Tests updated in `packages/server/tests/unit/tests/<module>.test.ts`
+
+## REST
+
+Follow the rules in `server.instructions.md`. Each module gets its own file under `src/rest/v1/<module>.ts` and must be mounted in `src/rest/v1/index.ts`.
+
+## MCP
+
+Each module operation must be exposed as an MCP tool in its own file at `src/mcp/tools/<module>.ts`. The file must export a `registerTools` function that accepts a `McpServer` instance. It must then be imported and called in `src/mcp/tools/index.ts`. Tool names follow the pattern `<verb>-<module>` (e.g., `list-files`, `create-user`). Tools call REST endpoints via `apiCall` using the same paths defined in the REST routes.
+
+## Docs
+
+Each module has a dedicated documentation page at `packages/website/docs/modules/<module>.md`. The page must describe:
+
+- What the module does (overview)
+- Key concepts and data model
+- Any roles or access rules that apply
+
+Do **not** document REST endpoints in the module docs — those are covered in the auto-generated API reference.
+
+## Tests
+
+Tests live in `packages/server/tests/unit/tests/<module>.test.ts`. Every public lib function and every REST route must have at least one test. Follow the patterns already established in `files.test.ts` and `users.test.ts`.

.github/instructions/postgresdb.instructions.md

@@ -8,3 +8,19 @@ description: Instructions for the PostgresDB package usage and integration.
 Check `#fetch https://ttoss.dev/docs/modules/packages/postgresdb/` for the official documentation of the `@ttoss/postgresdb` package used in this module.
 
 If you modify the database schema, ensure to make the tests pass by running `pnpm test` in the `packages/postgresdb`.
+
+## Public ID
+
+All models must have a `publicId` column (see `src/utils/publicId.ts`). The `publicId` is the only identifier exposed to external consumers. The internal `id` (UUID primary key) is for database-level joins only and must never be returned through any API or tool.
+
+When adding a new model, register a corresponding prefix in `src/utils/publicId.ts` (e.g., `user: 'usr_'`) and use it in the model's `beforeValidate` hook via `generatePublicId`.
+
+## Rebuilding After Model Changes
+
+After adding or modifying a model, rebuild the package so dependents (e.g., `@soat/server`) pick up the updated types:
+
+```bash
+pnpm --filter @soat/postgresdb build
+```
+
+Without this step, TypeScript in the server package will report errors like `Property 'User' does not exist on type`.