How do I install the Orienting skill?

Run npx skillmds@latest add jovandyaz/orienting in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Orienting safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Orienting?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Orienting free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.

Who published Orienting?

jovandyaz (@jovandyaz) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Orienting by jovandyaz — Agent Skill

Name: Orienting
Author: jovandyaz

Orienting

Orients architecture work in this Knowtis monorepo, including ownership, aliases, module boundaries, the two AI modules, and known framework footguns. Use when locating a subsystem, deciding where code belongs, reviewing architecture, or diagnosing a NestJS provider that is unexpectedly undefined. For generic Nx exploration use nx-workspace; for scaffolding use nx-generate. Not for copilot or collaboration internals.

jovandyaz 806afb6 3 files · 8.1 KB Updated Sep 17, 2026

File contents

Orienting in Knowtis

Knowtis is a real-time collaborative notes platform: Nx monorepo, pnpm, Node 22. React 19 + Vite frontend, NestJS 11 backend, PostgreSQL 16 + Drizzle, Redis, Yjs/Hocuspocus CRDT collaboration, Vercel AI SDK v6.

For the full layout and dependency rules load references/architecture-map.md. For Nx tags/boundaries and the dual alias namespaces load references/aliases-and-boundaries.md.

The five facts that prevent most wasted sessions

There are TWO AI modules. apps/api/src/modules/ai = single-shot AI features (inline assistant). apps/api/src/modules/agent = the conversational copilot (tool loop, HITL, threads). Both sit on the framework-free @knowtis/ai-gateway package. Don't add copilot features to ai or vice versa.
Two alias namespaces. 18 workspace entries import as @knowtis/*; publishable auth/permissions/email packages import as @jovandyaz/*. There is no @knowtis/auth — that import will not resolve.
The import type DI footgun. In apps/api/**, import type on a constructor-injected class silently breaks NestJS DI (provider arrives undefined). ESLint auto-fix is disabled there for this reason.
Migrations: generate + migrate, never push. Schema lives in apps/api/src/database/schema/; pnpm db:generate produces the migration; Railway's pre-deploy command is the only production migrator. drizzle-kit push against shared DBs causes the schema drift that migrations were adopted to fix.
Deploys are CI-driven, not Git-integration-driven. Notes and backoffice deploy to separate Vercel projects; API and MCP deploy through .github/scripts/railway-deploy.sh. Railway still applies watchPatterns to uploaded snapshots; SKIPPED means no new deployment became live and must be checked against Nx's affected set.

Working rules

Everything runs through Nx: pnpm nx affected -t lint test build, nx run <project> <target>. Always pnpm, never npm/yarn.
Module boundaries are ESLint-enforced via tags (type:app → type:ui/data-access → type:util; scopes shared|notes|api). A new lib needs correct tags or imports will be rejected.
AI features are gated: ANTHROPIC_API_KEY in env AND DB feature flags (ai_enabled, agent_byok, …) toggled on. A feature "not working" is often just a flag defaulting to off.
Repo docs are canonical: docs/ARCHITECTURE.md, docs/AI.md, docs/MCP.md, docs/AUTH.md, docs/PERMISSIONS.md, docs/MIGRATIONS.md, docs/DEPLOYMENT.md. Verify behavior against those docs and the current code rather than relying on historical design notes.

---name: orientingdescription: Orients architecture work in this Knowtis monorepo, including ownership, aliases, module boundaries, the two AI modules, and known framework footguns. Use when locating a subsystem, deciding where code belongs, reviewing architecture, or diagnosing a NestJS provider that is unexpectedly undefined. For generic Nx exploration use nx-workspace; for scaffolding use nx-generate. Not for copilot or collaboration internals.license: MIT---# Orienting in KnowtisKnowtis is a real-time collaborative notes platform: Nx monorepo, pnpm, Node 22. React 19 + Vite frontend, NestJS 11 backend, PostgreSQL 16 + Drizzle, Redis, Yjs/Hocuspocus CRDT collaboration, Vercel AI SDK v6.For the full layout and dependency rules load [references/architecture-map.md](references/architecture-map.md). For Nx tags/boundaries and the dual alias namespaces load [references/aliases-and-boundaries.md](references/aliases-and-boundaries.md).## The five facts that prevent most wasted sessions1. **There are TWO AI modules.** `apps/api/src/modules/ai` = single-shot AI features (inline assistant). `apps/api/src/modules/agent` = the conversational copilot (tool loop, HITL, threads). Both sit on the framework-free `@knowtis/ai-gateway` package. Don't add copilot features to `ai` or vice versa.2. **Two alias namespaces.** 18 workspace entries import as `@knowtis/*`; publishable auth/permissions/email packages import as `@jovandyaz/*`. There is no `@knowtis/auth` — that import will not resolve.3. **The `import type` DI footgun.** In `apps/api/**`, `import type` on a constructor-injected class silently breaks NestJS DI (provider arrives `undefined`). ESLint auto-fix is disabled there for this reason.4. **Migrations: `generate` + `migrate`, never `push`.** Schema lives in `apps/api/src/database/schema/`; `pnpm db:generate` produces the migration; Railway's pre-deploy command is the only production migrator. `drizzle-kit push` against shared DBs causes the schema drift that migrations were adopted to fix.5. **Deploys are CI-driven, not Git-integration-driven.** Notes and backoffice deploy to separate Vercel projects; API and MCP deploy through `.github/scripts/railway-deploy.sh`. Railway still applies `watchPatterns` to uploaded snapshots; `SKIPPED` means no new deployment became live and must be checked against Nx's affected set.## Working rules- Everything runs through Nx: `pnpm nx affected -t lint test build`, `nx run <project> <target>`. Always `pnpm`, never npm/yarn.- Module boundaries are ESLint-enforced via tags (`type:app → type:ui/data-access → type:util`; scopes `shared|notes|api`). A new lib needs correct tags or imports will be rejected.- AI features are gated: `ANTHROPIC_API_KEY` in env AND DB feature flags (`ai_enabled`, `agent_byok`, …) toggled on. A feature "not working" is often just a flag defaulting to off.- Repo docs are canonical: `docs/ARCHITECTURE.md`, `docs/AI.md`, `docs/MCP.md`, `docs/AUTH.md`, `docs/PERMISSIONS.md`, `docs/MIGRATIONS.md`, `docs/DEPLOYMENT.md`. Verify behavior against those docs and the current code rather than relying on historical design notes.

Frequently asked questions