feat: enhance README and issue templates with detailed guidelines and…

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,65 @@
+name: Bug Report
+description: Report a bug in permify-toolkit
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill in the details below so we can reproduce and fix it quickly.
+
+  - type: dropdown
+    id: package
+    attributes:
+      label: Affected Package
+      options:
+        - "@permify-toolkit/core"
+        - "@permify-toolkit/nestjs"
+        - "@permify-toolkit/cli"
+        - Multiple / unsure
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Package Version
+      placeholder: "e.g. 1.2.0"
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: A clear and concise description of the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal Reproduction
+      description: Code snippet or steps to reproduce the issue.
+      render: typescript
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: |
+        - Node version (`node -v`)
+        - pnpm version (`pnpm -v`)
+        - Permify server version (if relevant)
+      render: shell
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,52 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Have an idea that would make permify-toolkit better? We'd love to hear it!
+
+  - type: dropdown
+    id: package
+    attributes:
+      label: Which package does this affect?
+      options:
+        - "@permify-toolkit/core"
+        - "@permify-toolkit/nestjs"
+        - "@permify-toolkit/cli"
+        - New package / unsure
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / Motivation
+      description: What problem does this feature solve? What's the use case?
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe the API or behavior you'd like to see. Code examples welcome.
+      render: typescript
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any workarounds you've tried or alternative approaches.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Would you like to implement this?
+      options:
+        - label: "Yes, I'd like to open a PR for this feature"

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,31 @@
+## Summary
+
+<!-- What does this PR do? Why? -->
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation update
+- [ ] Refactor / chore
+
+## Affected Package(s)
+
+- [ ] `@permify-toolkit/core`
+- [ ] `@permify-toolkit/nestjs`
+- [ ] `@permify-toolkit/cli`
+- [ ] Simulator / docs
+
+## Checklist
+
+- [ ] I have read the [Contributing Guidelines](CONTRIBUTING.md)
+- [ ] My code follows the existing style (ran `pnpm lint` and `pnpm format:check`)
+- [ ] Tests are passing (`pnpm test`)
+- [ ] I have added/updated tests for new behavior
+- [ ] I have run `pnpm changeset` if this change affects a published package
+- [ ] Public API changes are reflected in `src/public-api.ts`
+
+## Related Issues
+
+<!-- Closes #xxx -->

AGENTS.md

@@ -0,0 +1,3 @@
+# AGENTS.md
+
+See [CLAUDE.md](./CLAUDE.md) for all AI assistant guidelines, architecture, and development standards.

CLAUDE.md

@@ -0,0 +1,147 @@
+# CLAUDE.md — Permify Toolkit
+
+## Project Goal
+
+Build a **type-safe, developer-first toolkit** for integrating [Permify](https://permify.co) into TypeScript applications. The toolkit abstracts gRPC complexity and provides idiomatic APIs for NestJS, CLI workflows, and shared config — so teams can manage fine-grained authorization in one place.
+
+## Architecture
+
+Monorepo with `pnpm` workspaces. Three published packages:
+
+| Package                   | Purpose                                                     |
+| ------------------------- | ----------------------------------------------------------- |
+| `@permify-toolkit/core`   | Schema DSL, client factory, permission/relationship helpers |
+| `@permify-toolkit/cli`    | CLI for pushing schemas and seeding relationships           |
+| `@permify-toolkit/nestjs` | NestJS module, guard, service, and decorators               |
+
+`/simulator` — reference implementation (NestJS backend + frontend).
+
+## Dev Commands
+
+```bash
+pnpm build          # build all packages
+pnpm dev            # watch mode for all packages
+pnpm test           # run all tests
+pnpm lint           # lint all packages
+pnpm format:check   # check formatting
+pnpm changeset      # create a changeset for release
+pnpm release        # build + publish to npm
+```
+
+## Goal-Driven Development Rules
+
+1. **Every change must serve a clear goal.** Before writing code, state the goal (bug fix, feature, DX improvement). Don't refactor unless it directly enables the goal.
+
+2. **Type safety is non-negotiable.** The schema DSL must remain fully type-safe. Avoid `any`. Prefer narrowing over casting.
+
+3. **No breaking changes without a changeset.** Run `pnpm changeset` and describe the impact before merging anything that changes public API.
+
+4. **Shared config is the source of truth.** `permify.config.ts` should be the single place teams define their Permify setup. CLI, NestJS, and tests all consume it — don't duplicate config paths.
+
+5. **Minimal surface area.** Only add to `public-api.ts` when a feature is complete and stable. Internal helpers stay internal.
+
+6. **Tests for every public function.** New exports in core/nestjs must have corresponding tests under `/tests` or the package's own test directory.
+
+## Conventions
+
+- **Commits**: Conventional commits enforced by commitlint (`feat:`, `fix:`, `chore:`, `docs:`, etc.)
+- **Formatting**: Prettier — run `pnpm format:check` before committing
+- **Package manager**: `pnpm` only — do not use `npm` or `yarn`
+- **Exports**: Each package exports via `src/public-api.ts` — keep this file clean and intentional
+
+## Release Flow
+
+1. Make changes in a feature branch
+2. `pnpm changeset` — describe what changed and bump type (patch/minor/major)
+3. PR → merge to `main`
+4. `pnpm version` — applies changeset, bumps package versions
+5. `pnpm release` — builds and publishes to npm
+
+## Key Files
+
+- `packages/core/src/public-api.ts` — all public exports for core
+- `packages/nestjs/src/module.ts` — PermifyModule (forRoot / forRootAsync)
+- `packages/nestjs/src/guard.ts` — PermifyGuard (multi-permission support)
+- `packages/cli/src/commands/` — CLI command implementations
+- `simulator/backend/` — reference NestJS app showing real-world usage
+
+---
+
+## AI Assistant Behavioral Guidelines
+
+These guidelines reduce common mistakes when working with AI assistants. Follow them to ensure quality contributions.
+
+### 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+
+- State your assumptions explicitly. If uncertain, ask clarifying questions.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+### 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If code exceeds ~150 lines when it could be ~50, rewrite it.
+
+Ask: "Would a senior engineer reviewing this say it's overcomplicated?" If yes, simplify.
+
+### 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if different.
+- If you notice unrelated dead code, mention it — don't delete it.
+
+When your changes create orphans:
+
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless explicitly asked.
+
+**The test**: Every changed line should trace directly to the user's request.
+
+### 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform vague tasks into verifiable goals:
+
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Improve the API" → "Show before/after usage in tests, then implement"
+
+For multi-step tasks, state a brief plan:
+
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria reduce back-and-forth. Weak criteria ("make it work") require constant clarification.
+
+### 5. Project-Specific Constraints
+
+When working with permify-toolkit:
+
+- **Always check** `packages/*/src/public-api.ts` before adding exports
+- **Run tests** after changes: `pnpm test`
+- **Verify types**: Ensure no `any` types leak into public APIs
+- **Use changesets**: Document breaking changes with `pnpm changeset`
+- **Match patterns**: Follow existing patterns in core/nestjs/cli packages
+
+---
+
+**Success indicators:** Fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come _before_ implementation rather than after mistakes.

README.md

@@ -9,6 +9,8 @@
 <a href="https://www.npmjs.com/package/@permify-toolkit/cli" target="_blank"><img src="https://img.shields.io/npm/v/@permify-toolkit/cli?label=%40permify-toolkit%2Fcli" alt="NPM Version" /></a>
 <a href="https://www.npmjs.com/package/@permify-toolkit/nestjs" target="_blank"><img src="https://img.shields.io/npm/v/@permify-toolkit/nestjs?label=%40permify-toolkit%2Fnestjs" alt="NPM Version" /></a>
 <a href="LICENSE" target="_blank"><img src="https://img.shields.io/github/license/thisisnkc/permify-toolkit" alt="Package License" /></a>
+<a href="https://github.com/thisisnkc/permify-toolkit/actions/workflows/ci.yml" target="_blank"><img src="https://github.com/thisisnkc/permify-toolkit/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+<a href="https://www.npmjs.com/package/@permify-toolkit/core" target="_blank"><img src="https://img.shields.io/npm/dm/@permify-toolkit/core?label=core%20downloads" alt="NPM Downloads" /></a>
 </p>
 
 <p align="center">
@@ -212,8 +214,18 @@ We're actively working on expanding the toolkit. Here's what's coming:
 - [x] Authorization guards for NestJS package
 - [x] Full-stack example app (frontend + NestJS backend)
 - [x] Release v1.0.0 and publish to npm
-- [x] Multi permission checks
+- [x] Multi permission checks (AND + OR logic)
 - [ ] Docs
+- [ ] Testing utilities — mock Permify client and test helpers for unit testing authorization logic
+- [ ] Permission result caching — in-memory (and optionally Redis-backed) cache to reduce gRPC round-trips
+- [ ] Schema validation CLI command — lint and validate schema syntax before pushing to Permify
+- [ ] Relationship query CLI commands — list, inspect, and export existing relationships from a tenant
+- [ ] Express.js / Fastify middleware — permission-check middleware for non-NestJS backends
+- [ ] GraphQL support — `@CheckPermission` directive and guards for NestJS GraphQL resolvers
+- [ ] ABAC helpers — high-level utilities for attribute-based access control rules
+- [ ] OpenTelemetry tracing — structured spans and metrics for permission checks and schema operations
+- [ ] Schema diff CLI command — preview what will change before pushing a schema update
+- [ ] Multi-tenant CLI management — create, list, and delete tenants directly from the CLI
 
 Have ideas? [Open an issue](https://github.com/thisisnkc/permify-toolkit/issues) or start a [discussion](https://github.com/thisisnkc/permify-toolkit/discussions)!
 

package.json

@@ -13,8 +13,19 @@
     "url": "git+https://github.com/thisisnkc/permify-toolkit.git"
   },
   "keywords": [
-    "toolkit",
-    "permify"
+    "permify",
+    "authorization",
+    "auth",
+    "permissions",
+    "rbac",
+    "abac",
+    "zanzibar",
+    "fine-grained-authorization",
+    "nestjs",
+    "grpc",
+    "typescript",
+    "access-control",
+    "toolkit"
   ],
   "main": "index.js",
   "scripts": {