{"owner":"logto-io","repo":"logto","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Project Instructions\n\n## Pull Requests\n\nWhen creating PRs:\n\n- If creating a branch, start it with the author's GitHub username (or another stable branch-safe identifier if unavailable), normalized to lowercase kebab-case, followed by lowercase kebab-case words, with no `/`.\n- Follow the repository PR template when available instead of duplicating it in instructions.\n- Do not describe feature flag details such as `isDevFeaturesEnabled` in the PR description.\n- In the `Testing` section, write `Tested locally`, `Unit tests`, `Integration tests`, or `N/A` as appropriate.\n- Do not mention build success, typecheck passing, or other CI-style checks in the `Testing` section.\n\n## Changesets\n\nChangesets and `isDevFeaturesEnabled` should not appear together for the same change. If a feature is split across multiple PRs, keep intermediate PRs behind `isDevFeaturesEnabled` without changesets; when releasing it, remove only that feature's guard and add its changeset.\n\nUnless explicitly requested otherwise, prefer `isDevFeaturesEnabled` over a changeset. New features should be protected by `isDevFeaturesEnabled` by default, unless the affected code is already inside an `isDevFeaturesEnabled` guard.\n\nStandalone bug fixes do not need `isDevFeaturesEnabled`, but bug-fix PRs should include a changeset when the fix affects released behavior.\n\nWhen adding a `.changeset` entry, prefer running `pnpm changeset` from the repository root.\n\nChangeset text should use this format:\n\n- First paragraph: one concise summary sentence.\n- The summary must start with a lowercase letter and omit the trailing period.\n- Optional following paragraph: detailed description when needed.\n- Write changeset text for the user-facing changelog. Describe the final product capability or behavior users can use.\n- Do not describe the release mechanics or implementation process, such as releasing a feature, removing a feature flag, or enabling an already-built feature.\n\n## Dev features\n\nWhen asked to remove `isDevFeaturesEnabled`, treat the request as scoped to one specific feature. Never remove all `isDevFeaturesEnabled` usage globally unless explicitly instructed otherwise.\n\nWhen adding `isDevFeaturesEnabled` for a new feature, include a comment that identifies the guarded feature at a high level. Prefer naming the broader feature area rather than a narrow implementation detail so the guard can be found and removed together when the feature is released.\n\nKeep public API changes backward-compatible. Do not rename existing fields, remove accepted inputs, or change released error semantics without an explicit product decision.\n\nWhen adding or changing API behavior, update the corresponding OpenAPI document in the same PR. For an in-development API, use `tags: [\"Dev feature\"]` to guard an entire operation, or set `x-logto-dev-feature: true` on an individual schema property. These markers keep in-development API surfaces out of public OpenAPI output when dev features are disabled.\n\n## Localization\n\nWhen changing copy under `packages/phrases`, sync and translate the corresponding entries for the other locale files in the same PR unless the change is intentionally source-locale only.\n\n## Lint and TypeScript Suppressions\n\nEvery `eslint-disable` and `@ts-expect-error` must include a short reason explaining why the suppression is safe or necessary.\n\n## Commit Hook Discipline\n\nNever bypass commit hooks.\n\nMany packages in this project depend on each other through built artifacts. When checks fail because local package outputs are stale or missing, run `pnpm prepack` to rebuild them before retrying.\n\nIf a hook cannot be fixed safely within the current task, stop and report the blocker with the failed command, relevant output, why it is out of scope, and what decision is needed.\n\n## Cursor Cloud specific instructions\n\n### Services overview\n\n| Service | Port | Purpose |\n|---------|------|---------|\n| PostgreSQL | 5432 | Primary data store (required) |\n| Logto Core | 3001 (user), 3002 (admin) | Backend: OIDC provider + Management API |\n| Console (Vite) | 5002 | Admin dashboard SPA |\n| Experience (Vite) | 5001 | Sign-in experience SPA |\n\n### Starting the development environment\n\n1. Start Docker daemon: `sudo dockerd &>/tmp/dockerd.log &` then `sudo chmod 666 /var/run/docker.sock`\n2. Start PostgreSQL: `docker run -d --name logto-postgres -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=p0stgr3s -e POSTGRES_DB=logto postgres:17-alpine`\n3. Set env: `export DB_URL=\"postgres://postgres:p0stgr3s@localhost:5432/logto\"`\n4. If first run (empty database): `pnpm cli db seed` and `pnpm cli connector link -p .`\n5. If Core exits with undeployed alterations on an existing database: `pnpm alteration deploy` with the version in `packages/schemas/package.json`, then `pnpm alteration deploy next`\n6. Start dev: `pnpm start:dev` (skip `pnpm dev` which re-runs prepack; prepack is already done by the update script)\n\n### Optional dev workflows (skills)\n\nSkills live under [.agents/skills/](.agents/skills/) ([Agent Skills](https://agentskills.io) format; Cursor Cloud and other agents discover `.agents/skills/` and `.cursor/skills/`). Read a skill **only when the task needs it**—do not load full command lists into context unless relevant.\n\n| Skill | Read when |\n|-------|-----------|\n| [.agents/skills/logto-dev-environment/SKILL.md](.agents/skills/logto-dev-environment/SKILL.md) | Local dev environment bootstrap, database seed/alteration, service health checks, localhost smoke tests, Experience `/demo-app` walkthroughs |\n| [.agents/skills/logto-local-storage/SKILL.md](.agents/skills/logto-local-storage/SKILL.md) | Avatar/file upload, `storage.not_configured`, `user-assets`, collect-profile **avatar** field |\n\n### Key caveats\n\n- `rsync` must be installed (needed by `@logto/core` for `copy:apidocs`). Install with `sudo apt-get install -y rsync` if missing.\n- Connector load errors at startup are expected in dev mode — connectors are not built by default (`pnpm start:dev` excludes them).\n- `@logto/core` unit tests require `pnpm build:test` in `packages/core` before running `pnpm test:only`, because Jest reads from `./build` (the tsup dev bundle doesn't include test files).\n- `@logto/elements` tests require Playwright browsers: run `pnpm exec playwright install chromium --with-deps` inside `packages/elements`.\n- The pre-commit hook runs `lint-staged` on changed packages; if it fails due to stale outputs, run `pnpm prepack` first.\n- `pnpm install` runs `sync-preset` over every `packages/connectors/connector-*` directory; orphan connector folders without `package.json` (not in git) will break install—remove them before `pnpm install`.\n\n### Running tests and lint\n\n- Lint: `pnpm ci:lint` (ESLint) and `pnpm ci:stylelint` (Stylelint) from repo root.\n- Unit tests: `pnpm ci:test` from repo root runs all package tests in parallel.\n- Individual package tests: `pnpm test` inside the package directory.\n- See `.github/CONTRIBUTING.md` for integration test instructions (Docker-based).\n"},"files":{"AGENTS.md":"# Project Instructions\n\n## Pull Requests\n\nWhen creating PRs:\n\n- If creating a branch, start it with the author's GitHub username (or another stable branch-safe identifier if unavailable), normalized to lowercase kebab-case, followed by lowercase kebab-case words, with no `/`.\n- Follow the repository PR template when available instead of duplicating it in instructions.\n- Do not describe feature flag details such as `isDevFeaturesEnabled` in the PR description.\n- In the `Testing` section, write `Tested locally`, `Unit tests`, `Integration tests`, or `N/A` as appropriate.\n- Do not mention build success, typecheck passing, or other CI-style checks in the `Testing` section.\n\n## Changesets\n\nChangesets and `isDevFeaturesEnabled` should not appear together for the same change. If a feature is split across multiple PRs, keep intermediate PRs behind `isDevFeaturesEnabled` without changesets; when releasing it, remove only that feature's guard and add its changeset.\n\nUnless explicitly requested otherwise, prefer `isDevFeaturesEnabled` over a changeset. New features should be protected by `isDevFeaturesEnabled` by default, unless the affected code is already inside an `isDevFeaturesEnabled` guard.\n\nStandalone bug fixes do not need `isDevFeaturesEnabled`, but bug-fix PRs should include a changeset when the fix affects released behavior.\n\nWhen adding a `.changeset` entry, prefer running `pnpm changeset` from the repository root.\n\nChangeset text should use this format:\n\n- First paragraph: one concise summary sentence.\n- The summary must start with a lowercase letter and omit the trailing period.\n- Optional following paragraph: detailed description when needed.\n- Write changeset text for the user-facing changelog. Describe the final product capability or behavior users can use.\n- Do not describe the release mechanics or implementation process, such as releasing a feature, removing a feature flag, or enabling an already-built feature.\n\n## Dev features\n\nWhen asked to remove `isDevFeaturesEnabled`, treat the request as scoped to one specific feature. Never remove all `isDevFeaturesEnabled` usage globally unless explicitly instructed otherwise.\n\nWhen adding `isDevFeaturesEnabled` for a new feature, include a comment that identifies the guarded feature at a high level. Prefer naming the broader feature area rather than a narrow implementation detail so the guard can be found and removed together when the feature is released.\n\nKeep public API changes backward-compatible. Do not rename existing fields, remove accepted inputs, or change released error semantics without an explicit product decision.\n\nWhen adding or changing API behavior, update the corresponding OpenAPI document in the same PR. For an in-development API, use `tags: [\"Dev feature\"]` to guard an entire operation, or set `x-logto-dev-feature: true` on an individual schema property. These markers keep in-development API surfaces out of public OpenAPI output when dev features are disabled.\n\n## Localization\n\nWhen changing copy under `packages/phrases`, sync and translate the corresponding entries for the other locale files in the same PR unless the change is intentionally source-locale only.\n\n## Lint and TypeScript Suppressions\n\nEvery `eslint-disable` and `@ts-expect-error` must include a short reason explaining why the suppression is safe or necessary.\n\n## Commit Hook Discipline\n\nNever bypass commit hooks.\n\nMany packages in this project depend on each other through built artifacts. When checks fail because local package outputs are stale or missing, run `pnpm prepack` to rebuild them before retrying.\n\nIf a hook cannot be fixed safely within the current task, stop and report the blocker with the failed command, relevant output, why it is out of scope, and what decision is needed.\n\n## Cursor Cloud specific instructions\n\n### Services overview\n\n| Service | Port | Purpose |\n|---------|------|---------|\n| PostgreSQL | 5432 | Primary data store (required) |\n| Logto Core | 3001 (user), 3002 (admin) | Backend: OIDC provider + Management API |\n| Console (Vite) | 5002 | Admin dashboard SPA |\n| Experience (Vite) | 5001 | Sign-in experience SPA |\n\n### Starting the development environment\n\n1. Start Docker daemon: `sudo dockerd &>/tmp/dockerd.log &` then `sudo chmod 666 /var/run/docker.sock`\n2. Start PostgreSQL: `docker run -d --name logto-postgres -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=p0stgr3s -e POSTGRES_DB=logto postgres:17-alpine`\n3. Set env: `export DB_URL=\"postgres://postgres:p0stgr3s@localhost:5432/logto\"`\n4. If first run (empty database): `pnpm cli db seed` and `pnpm cli connector link -p .`\n5. If Core exits with undeployed alterations on an existing database: `pnpm alteration deploy` with the version in `packages/schemas/package.json`, then `pnpm alteration deploy next`\n6. Start dev: `pnpm start:dev` (skip `pnpm dev` which re-runs prepack; prepack is already done by the update script)\n\n### Optional dev workflows (skills)\n\nSkills live under [.agents/skills/](.agents/skills/) ([Agent Skills](https://agentskills.io) format; Cursor Cloud and other agents discover `.agents/skills/` and `.cursor/skills/`). Read a skill **only when the task needs it**—do not load full command lists into context unless relevant.\n\n| Skill | Read when |\n|-------|-----------|\n| [.agents/skills/logto-dev-environment/SKILL.md](.agents/skills/logto-dev-environment/SKILL.md) | Local dev environment bootstrap, database seed/alteration, service health checks, localhost smoke tests, Experience `/demo-app` walkthroughs |\n| [.agents/skills/logto-local-storage/SKILL.md](.agents/skills/logto-local-storage/SKILL.md) | Avatar/file upload, `storage.not_configured`, `user-assets`, collect-profile **avatar** field |\n\n### Key caveats\n\n- `rsync` must be installed (needed by `@logto/core` for `copy:apidocs`). Install with `sudo apt-get install -y rsync` if missing.\n- Connector load errors at startup are expected in dev mode — connectors are not built by default (`pnpm start:dev` excludes them).\n- `@logto/core` unit tests require `pnpm build:test` in `packages/core` before running `pnpm test:only`, because Jest reads from `./build` (the tsup dev bundle doesn't include test files).\n- `@logto/elements` tests require Playwright browsers: run `pnpm exec playwright install chromium --with-deps` inside `packages/elements`.\n- The pre-commit hook runs `lint-staged` on changed packages; if it fails due to stale outputs, run `pnpm prepack` first.\n- `pnpm install` runs `sync-preset` over every `packages/connectors/connector-*` directory; orphan connector folders without `package.json` (not in git) will break install—remove them before `pnpm install`.\n\n### Running tests and lint\n\n- Lint: `pnpm ci:lint` (ESLint) and `pnpm ci:stylelint` (Stylelint) from repo root.\n- Unit tests: `pnpm ci:test` from repo root runs all package tests in parallel.\n- Individual package tests: `pnpm test` inside the package directory.\n- See `.github/CONTRIBUTING.md` for integration test instructions (Docker-based).\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Project Instructions\n\n## Pull Requests\n\nWhen creating PRs:\n\n- If creating a branch, start it with the author's GitHub username (or another stable branch-safe identifier if unavailable), normalized to lowercase kebab-case, followed by lowercase kebab-case words, with no `/`.\n- Follow the repository PR template when available instead of duplicating it in instructions.\n- Do not describe feature flag details such as `isDevFeaturesEnabled` in the PR description.\n- In the `Testing` section, write `Tested locally`, `Unit tests`, `Integration tests`, or `N/A` as appropriate.\n- Do not mention build success, typecheck passing, or other CI-style checks in the `Testing` section.\n\n## Changesets\n\nChangesets and `isDevFeaturesEnabled` should not appear together for the same change. If a feature is split across multiple PRs, keep intermediate PRs behind `isDevFeaturesEnabled` without changesets; when releasing it, remove only that feature's guard and add its changeset.\n\nUnless explicitly requested otherwise, prefer `isDevFeaturesEnabled` over a changeset. New features should be protected by `isDevFeaturesEnabled` by default, unless the affected code is already inside an `isDevFeaturesEnabled` guard.\n\nStandalone bug fixes do not need `isDevFeaturesEnabled`, but bug-fix PRs should include a changeset when the fix affects released behavior.\n\nWhen adding a `.changeset` entry, prefer running `pnpm changeset` from the repository root.\n\nChangeset text should use this format:\n\n- First paragraph: one concise summary sentence.\n- The summary must start with a lowercase letter and omit the trailing period.\n- Optional following paragraph: detailed description when needed.\n- Write changeset text for the user-facing changelog. Describe the final product capability or behavior users can use.\n- Do not describe the release mechanics or implementation process, such as releasing a feature, removing a feature flag, or enabling an already-built feature.\n\n## Dev features\n\nWhen asked to remove `isDevFeaturesEnabled`, treat the request as scoped to one specific feature. Never remove all `isDevFeaturesEnabled` usage globally unless explicitly instructed otherwise.\n\nWhen adding `isDevFeaturesEnabled` for a new feature, include a comment that identifies the guarded feature at a high level. Prefer naming the broader feature area rather than a narrow implementation detail so the guard can be found and removed together when the feature is released.\n\nKeep public API changes backward-compatible. Do not rename existing fields, remove accepted inputs, or change released error semantics without an explicit product decision.\n\nWhen adding or changing API behavior, update the corresponding OpenAPI document in the same PR. For an in-development API, use `tags: [\"Dev feature\"]` to guard an entire operation, or set `x-logto-dev-feature: true` on an individual schema property. These markers keep in-development API surfaces out of public OpenAPI output when dev features are disabled.\n\n## Localization\n\nWhen changing copy under `packages/phrases`, sync and translate the corresponding entries for the other locale files in the same PR unless the change is intentionally source-locale only.\n\n## Lint and TypeScript Suppressions\n\nEvery `eslint-disable` and `@ts-expect-error` must include a short reason explaining why the suppression is safe or necessary.\n\n## Commit Hook Discipline\n\nNever bypass commit hooks.\n\nMany packages in this project depend on each other through built artifacts. When checks fail because local package outputs are stale or missing, run `pnpm prepack` to rebuild them before retrying.\n\nIf a hook cannot be fixed safely within the current task, stop and report the blocker with the failed command, relevant output, why it is out of scope, and what decision is needed.\n\n## Cursor Cloud specific instructions\n\n### Services overview\n\n| Service | Port | Purpose |\n|---------|------|---------|\n| PostgreSQL | 5432 | Primary data store (required) |\n| Logto Core | 3001 (user), 3002 (admin) | Backend: OIDC provider + Management API |\n| Console (Vite) | 5002 | Admin dashboard SPA |\n| Experience (Vite) | 5001 | Sign-in experience SPA |\n\n### Starting the development environment\n\n1. Start Docker daemon: `sudo dockerd &>/tmp/dockerd.log &` then `sudo chmod 666 /var/run/docker.sock`\n2. Start PostgreSQL: `docker run -d --name logto-postgres -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=p0stgr3s -e POSTGRES_DB=logto postgres:17-alpine`\n3. Set env: `export DB_URL=\"postgres://postgres:p0stgr3s@localhost:5432/logto\"`\n4. If first run (empty database): `pnpm cli db seed` and `pnpm cli connector link -p .`\n5. If Core exits with undeployed alterations on an existing database: `pnpm alteration deploy` with the version in `packages/schemas/package.json`, then `pnpm alteration deploy next`\n6. Start dev: `pnpm start:dev` (skip `pnpm dev` which re-runs prepack; prepack is already done by the update script)\n\n### Optional dev workflows (skills)\n\nSkills live under [.agents/skills/](.agents/skills/) ([Agent Skills](https://agentskills.io) format; Cursor Cloud and other agents discover `.agents/skills/` and `.cursor/skills/`). Read a skill **only when the task needs it**—do not load full command lists into context unless relevant.\n\n| Skill | Read when |\n|-------|-----------|\n| [.agents/skills/logto-dev-environment/SKILL.md](.agents/skills/logto-dev-environment/SKILL.md) | Local dev environment bootstrap, database seed/alteration, service health checks, localhost smoke tests, Experience `/demo-app` walkthroughs |\n| [.agents/skills/logto-local-storage/SKILL.md](.agents/skills/logto-local-storage/SKILL.md) | Avatar/file upload, `storage.not_configured`, `user-assets`, collect-profile **avatar** field |\n\n### Key caveats\n\n- `rsync` must be installed (needed by `@logto/core` for `copy:apidocs`). Install with `sudo apt-get install -y rsync` if missing.\n- Connector load errors at startup are expected in dev mode — connectors are not built by default (`pnpm start:dev` excludes them).\n- `@logto/core` unit tests require `pnpm build:test` in `packages/core` before running `pnpm test:only`, because Jest reads from `./build` (the tsup dev bundle doesn't include test files).\n- `@logto/elements` tests require Playwright browsers: run `pnpm exec playwright install chromium --with-deps` inside `packages/elements`.\n- The pre-commit hook runs `lint-staged` on changed packages; if it fails due to stale outputs, run `pnpm prepack` first.\n- `pnpm install` runs `sync-preset` over every `packages/connectors/connector-*` directory; orphan connector folders without `package.json` (not in git) will break install—remove them before `pnpm install`.\n\n### Running tests and lint\n\n- Lint: `pnpm ci:lint` (ESLint) and `pnpm ci:stylelint` (Stylelint) from repo root.\n- Unit tests: `pnpm ci:test` from repo root runs all package tests in parallel.\n- Individual package tests: `pnpm test` inside the package directory.\n- See `.github/CONTRIBUTING.md` for integration test instructions (Docker-based).\n","category":"root","tokens":1755}]}