### Configure and Build Self-Hosted Backend

Source: https://context7.com/nexus-jpf/note-companion/llms.txt

Clone the repository, install dependencies, and configure environment variables in `packages/web/.env`. Then build and start the self-hosted server.

```bash
git clone https://github.com/Nexus-JPF/note-companion.git
cd note-companion
pnpm install

cat > packages/web/.env << 'EOF'
# At least one AI provider is required
OPENAI_API_KEY=sk-...

# Optional additional providers
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_GENERATIVE_AI_API_KEY=...
GROQ_API_KEY=gsk_...
MISTRAL_API_KEY=...
DEEPSEEK_API_KEY=...

# Provider selection (defaults to openai + gpt-4o-mini)
MODEL_PROVIDER=openai
MODEL_NAME=gpt-4o-mini

# Whisper on a separate host (optional)
OPENAI_WHISPER_BASE_URL=http://localhost:9000/v1

# Disable Unkey user management for self-hosting
ENABLE_USER_MANAGEMENT=false

# Server
PORT=3000
NODE_ENV=production

# Optional: PostgreSQL (defaults to SQLite)
DATABASE_URL=postgresql://user:pass@localhost:5432/notecompanion
EOF

# Build and start
cd packages/web
pnpm build:self-host
pnpm start
# → Ready at http://localhost:3000
```

--------------------------------

### Start Application with PM2

Source: https://github.com/nexus-jpf/note-companion/blob/master/SELF-HOSTING.md

Starts the Note Companion application using PM2, names the process, saves the current process list for auto-start, and initiates the setup for auto-starting PM2 on system boot.

```bash
cd packages/web
pm2 start "pnpm start" --name note-companion
pm2 save
pm2 startup  # Follow the instructions to enable auto-start
```

--------------------------------

### Navigate to Mobile Directory and Run Start

Source: https://github.com/nexus-jpf/note-companion/blob/master/CONTRIBUTING.md

Change directory to the mobile application package and start its development environment.

```bash
cd packages/mobile
pnpm start
```

--------------------------------

### Enable and Start systemd Service

Source: https://github.com/nexus-jpf/note-companion/blob/master/SELF-HOSTING.md

Commands to enable the Note Companion service to start on boot and to start it immediately.

```bash
sudo systemctl enable note-companion
sudo systemctl start note-companion
```

--------------------------------

### Start the Development Server

Source: https://github.com/nexus-jpf/note-companion/blob/master/packages/mobile/README.md

Starts the Expo development server. This command is an alias for 'npx expo start'.

```bash
pnpm start
```

--------------------------------

### Start the Production Server

Source: https://github.com/nexus-jpf/note-companion/blob/master/SELF-HOSTING.md

Start the Note Companion server in production mode. The server will run on the port specified in the PORT environment variable, defaulting to 3000.

```bash
# Start the production server
pnpm start
```

--------------------------------

### Navigate to Plugin Directory and Run Dev

Source: https://github.com/nexus-jpf/note-companion/blob/master/CONTRIBUTING.md

Change directory to the plugin package and start its development server.

```bash
cd packages/plugin
pnpm dev
```

--------------------------------

### Install Dependencies with Yarn

Source: https://github.com/nexus-jpf/note-companion/blob/master/REACT_HOOKS_ERROR_FIX.md

After configuring Yarn and cleaning up pnpm artifacts, run 'yarn install' to install all project dependencies using Yarn.

```bash
yarn install
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/nexus-jpf/note-companion/blob/master/SELF-HOSTING.md

Clone the Note Companion repository and install project dependencies using pnpm.

```bash
git clone https://github.com/Nexus-JPF/note-companion.git
cd note-companion

pnpm install
```

--------------------------------

### Subscription Sync Script Output Example

Source: https://github.com/nexus-jpf/note-companion/blob/master/packages/web/scripts/README.md

Example output from the subscription sync script, showing the progress and summary of synced, not found, and errored subscriptions.

```text
Starting subscription sync...

Found 150 subscription users to sync

✓ Synced user_123: active (monthly)
✓ Synced user_456: active (yearly)
⚠ No Stripe subscription found for user_789
✗ Error syncing user_999: API error

=== Sync Complete ===
✓ Synced: 145
⚠ Not found in Stripe: 3
✗ Errors: 2
Total: 150
```

--------------------------------

### Navigate to Landing Directory and Run Dev

Source: https://github.com/nexus-jpf/note-companion/blob/master/CONTRIBUTING.md

Change directory to the landing page package and start its development server.

```bash
cd packages/landing
pnpm dev
```

--------------------------------

### Start the App on iOS

Source: https://github.com/nexus-jpf/note-companion/blob/master/packages/mobile/README.md

Execute this command to build and run the application on an iOS device or simulator.

```bash
pnpm ios
```

--------------------------------

### Install Dependencies and Build Project

Source: https://github.com/nexus-jpf/note-companion/blob/master/AGENTS.MD

Commands to install project dependencies using pnpm, build all packages, and run specific packages in development mode.

```bash
# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run specific package
cd packages/web
pnpm dev

cd packages/plugin
pnpm dev

cd packages/mobile
pnpm start
```

--------------------------------

### Start the App on Android

Source: https://github.com/nexus-jpf/note-companion/blob/master/packages/mobile/README.md

Execute this command to build and run the application on an Android device or emulator.

```bash
pnpm android
```

--------------------------------

### Navigate to Web Directory and Run Dev

Source: https://github.com/nexus-jpf/note-companion/blob/master/CONTRIBUTING.md

Change directory to the web application package and start its development server. Note the default port.

```bash
cd packages/web
pnpm dev  # Runs on port 3010
```

--------------------------------

### Install Yarn and Configure Node Linker

Source: https://github.com/nexus-jpf/note-companion/blob/master/REACT_HOOKS_ERROR_FIX.md

Switch to Yarn v3+ by installing it using corepack and configuring the nodeLinker to 'node-modules' and nmHoistingLimits to 'workspaces' in .yarnrc.yml.

```bash
corepack enable
yarn set version stable
```

```yaml
nodeLinker: node-modules
nmHoistingLimits: workspaces

```

--------------------------------

### Install AI Elements Components

Source: https://github.com/nexus-jpf/note-companion/blob/master/AI_SDK_ELEMENTS_MIGRATION.md

Add specific AI Elements components to your project. Ensure you install all required components for your use case.

```bash
npx ai-elements@latest add conversation message response prompt-input actions tool code-block
```

--------------------------------

### Tool Chain Example for Information Gathering

Source: https://github.com/nexus-jpf/note-companion/blob/master/IMPLEMENTATION-LOCAL-TOOLS.md

Demonstrates a typical tool chain for an AI model to gather comprehensive information about a specific note, starting with searching for the note and then retrieving its metadata.

```plaintext
getSearchQuery(query: "machine learning") 
  → Get file paths
  → getFileMetadata(paths: results, includeAll: true)
  → Present comprehensive information
```

--------------------------------

### Define Default Processing Presets

Source: https://github.com/nexus-jpf/note-companion/blob/master/ORGANIZER_BEHAVIOR_ANALYSIS.md

Provides example configurations for common file types like research papers, meeting notes, and YouTube videos. These presets can be used as a starting point or directly integrated into the application.

```typescript
// Example presets
const DEFAULT_PRESETS: ProcessingPreset[] = [
  {
    id: 'research-paper',
    name: 'Research Paper',
    icon: '📄',
    description: 'For academic papers (PDFs)',
    settings: {
      classification: 'research_paper',
      folder: 'Research/Papers',
      tags: ['#research', '#academic'],
      template: 'research_paper.md',
      formatBehavior: 'override',
    },
    filePattern: '*.pdf',
  },
  {
    id: 'meeting-notes',
    name: 'Meeting Notes',
    icon: '🗓️',
    description: 'For recorded meetings',
    settings: {
      classification: 'meeting_note',
      folder: 'Meetings',
      tags: ['#meeting'],
      template: 'meeting_note.md',
      formatBehavior: 'override',
    },
    filePattern: 'meeting-*.{mp3,m4a,wav}',
  },
  {
    id: 'youtube-video',
    name: 'YouTube Video',
    icon: '📺',
    description: 'For YouTube video notes',
    settings: {
      classification: 'youtube_video',
      folder: 'Videos/YouTube',
      tags: ['#youtube', '#video'],
      template: 'youtube_video.md',
      formatBehavior: 'override',
    },
    filePattern: '*youtube*.md',
  },
];
```

--------------------------------

### Self-Hosting Setup with Docker

Source: https://context7.com/nexus-jpf/note-companion/llms.txt

Instructions for deploying the Note Companion backend using Docker Compose for a self-hosted environment.

```APIDOC
## Self-Hosting Setup with Docker Compose

Deploy the backend with Docker Compose. All AI provider keys and configurations should be placed in `packages/web/.env`.

```bash
# Clone and install dependencies
git clone https://github.com/Nexus-JPF/note-companion.git
cd note-companion
pnpm install

# Configure environment variables (example for packages/web/.env)
cat > packages/web/.env << 'EOF' 
OPENAI_API_KEY=sk-...
MODEL_PROVIDER=openai
MODEL_NAME=gpt-4o-mini
ENABLE_USER_MANAGEMENT=false
PORT=3000
NODE_ENV=production
EOF

# Start the server using Docker Compose
docker compose up -d

# Verify server health
curl http://localhost:3000/api/health
# Expected output: {"status":"ok"}
```
```

--------------------------------

### Run All Packages in Development Mode

Source: https://github.com/nexus-jpf/note-companion/blob/master/CONTRIBUTING.md

Start all packages in development mode simultaneously. Ensure environment variables are set up.

```bash
pnpm dev
```

--------------------------------

### Good UI Component Example (Obsidian Core Style)

Source: https://github.com/nexus-jpf/note-companion/blob/master/AGENTS.MD

This example follows Obsidian's styling guidelines, using CSS variables for borders, text, and hover effects, and a flat design.

```tsx
<div className="border-b border-[--background-modifier-border] p-2 hover:bg-[--background-modifier-hover]">
  <div className="text-[--font-ui-smaller] font-semibold text-[--text-muted] uppercase mb-1">
    Section Header
  </div>
  <div className="flex items-center gap-2">
    <span className="text-[--text-normal]">Content</span>
    <button className="clickable-icon" aria-label="Action">
      <svg className="w-[--icon-size] h-[--icon-size]">...</svg>
    </button>
  </div>
</div>
```

--------------------------------

### Initialize AI Elements

Source: https://github.com/nexus-jpf/note-companion/blob/master/AI_SDK_ELEMENTS_MIGRATION.md

Run this command to set up AI Elements in your project. It installs the necessary packages and configurations.

```bash
npx ai-elements@latest init
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/nexus-jpf/note-companion/blob/master/CONTRIBUTING.md

Install project dependencies using pnpm, the package manager for this monorepo.

```bash
pnpm install
```

--------------------------------

### Bad UI Component Example (SaaS Dashboard Style)

Source: https://github.com/nexus-jpf/note-companion/blob/master/AGENTS.MD

This example demonstrates an anti-pattern for UI components, resembling a SaaS dashboard with hardcoded colors and heavy shadows.

```tsx
<div className="bg-white shadow-lg rounded-xl p-6 m-4">
  <h2 className="text-2xl font-bold text-gray-900 mb-4">My Card</h2>
  <button className="bg-blue-500 text-white px-6 py-3 rounded-lg">
    Click Me
  </button>
</div>
```

--------------------------------

### Run Next.js Local Development Server

Source: https://github.com/nexus-jpf/note-companion/blob/master/packages/landing/README.md

Start the local development server for your Next.js application. The starter kit will be accessible at http://localhost:3000.

```bash
npm run dev
```

--------------------------------

### Find Active Subscriptions Script Output Example

Source: https://github.com/nexus-jpf/note-companion/blob/master/packages/web/scripts/README.md

Example output from the find active subscriptions script, detailing total and active subscriptions, status breakdown, individual subscription details, revenue, and metadata status.

```text
=== Finding All Active Subscriptions ===

Total subscriptions (all statuses): 45
Active/Trialing subscriptions: 12

=== Status Breakdown ===
  active: 12
  canceled: 30
  past_due: 2
  unpaid: 1

=== Active Subscriptions ===

1. Subscription ID: sub_1Abc123
   User ID: user_2xyz789
   Status: active
   Interval: month
   Amount: 15.00 USD
   Created: 2025-01-15
   Current Period Ends: 2025-11-15
   Customer: cus_ABC123

=== Active Subscriptions by Interval ===
  month: 8
  year: 4

=== Revenue ===
  MRR (Monthly Recurring Revenue): $163.33
  ARR (Annual Recurring Revenue): $1960.00

=== Metadata Status ===
  With userId metadata: 11
  Without userId metadata: 1

  ⚠️ Subscriptions without userId:
    - sub_1Def456 (customer: cus_DEF456)

=== Recently Canceled (last 5) ===

1. sub_1Ghi789
   User ID: user_2abc123
   Canceled: 2025-10-01
   Cancellation reason: cancellation_requested
```

--------------------------------

### Install PM2 Process Manager

Source: https://github.com/nexus-jpf/note-companion/blob/master/SELF-HOSTING.md

Installs PM2 globally, which is a production process manager for Node.js applications.

```bash
npm install -g pm2
```

--------------------------------

### Install Dependencies After Package Updates

Source: https://github.com/nexus-jpf/note-companion/blob/master/REACT_HOOKS_ERROR_FIX.md

Navigate to the mobile package directory and run pnpm install to update dependencies based on the modified package.json or workspace catalog.

```bash
cd packages/mobile
pnpm install
```

--------------------------------

### Create Next.js App with Supabase Starter

Source: https://github.com/nexus-jpf/note-companion/blob/master/packages/landing/README.md

Use this command to scaffold a new Next.js project with the Supabase Starter template. Ensure you have Node.js and npm/yarn installed.

```bash
npx create-next-app -e with-supabase
```

--------------------------------

### Test Mobile App with Expo

Source: https://github.com/nexus-jpf/note-companion/blob/master/REACT_HOOKS_ERROR_FIX.md

Commands to start the mobile application using Expo and run it on an emulator or device.

```bash
cd packages/mobile
pnpm start
# Then press 'i' or 'a'
```

--------------------------------

### Usage Example with CSS Variables and tw()

Source: https://github.com/nexus-jpf/note-companion/blob/master/ASSISTANT_STYLING_ANALYSIS.md

An example demonstrating how to use Obsidian CSS variables with the `tw()` utility for styling a button. This ensures the button is themeable and responsive to dark mode.

```tsx
<button className={tw(
  "px-4 py-2",
  "bg-[--interactive-accent] text-[--text-on-accent]",
  "hover:bg-[--interactive-accent-hover]",
  "border border-[--background-modifier-border]",
  "rounded-md transition-colors"
)}>
  Click Me
</button>
```

--------------------------------

### Beta Release Manifest (JSON)

Source: https://github.com/nexus-jpf/note-companion/blob/master/BACKWARD_COMPATIBILITY_STRATEGY.md

Example `manifest.json` configuration for a beta release of the plugin, specifying version '2.3.0-beta' and targeting a minimum app version.

```json
// manifest.json
{
  "version": "2.3.0-beta",
  "minAppVersion": "1.0.0"
}
```

--------------------------------

### Deploy Backend with Docker Compose

Source: https://context7.com/nexus-jpf/note-companion/llms.txt

Use Docker Compose for a simplified deployment. After starting, verify the server's health using a curl command.

```bash
# Or with Docker Compose (uses the provided docker-compose.yml)
docker compose up -d

# Verify server health
curl http://localhost:3000/api/health
# → {"status":"ok"}
```

--------------------------------

### Canary Release Manifest (JSON)

Source: https://github.com/nexus-jpf/note-companion/blob/master/BACKWARD_COMPATIBILITY_STRATEGY.md

Example `manifest.json` configuration for a canary release of the plugin, specifying version '2.3.0'.

```json
{
  "version": "2.3.0",
}
```

--------------------------------

### Dockerfile for Note Companion

Source: https://github.com/nexus-jpf/note-companion/blob/master/SELF-HOSTING.md

A Dockerfile to build a self-hosted image for Note Companion. It installs dependencies, builds the self-hostable version, and exposes the application port.

```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY . .
RUN npm install -g pnpm
RUN pnpm install
WORKDIR /app/packages/web
RUN pnpm build:self-host
EXPOSE 3000
CMD ["pnpm", "start"]
```

--------------------------------

### Define New Tool on Server

Source: https://github.com/nexus-jpf/note-companion/blob/master/IMPLEMENTATION-LOCAL-TOOLS.md

Example of how to define a new tool within the server-side API, including its description and parameters using Zod schema.

```typescript
// packages/web/app/api/(newai)/chat/tools.ts
export const chatTools = {
  // ... existing tools
  
  myNewTool: {
    description: "Clear description for AI",
    parameters: z.object({
      param1: z.string().describe("What this parameter does"),
    }),
  },
};
```

--------------------------------

### AI Chat Command Examples

Source: https://github.com/nexus-jpf/note-companion/blob/master/docs/GPT-4.1-MINI-USAGE.md

Demonstrates typical user interactions and expected GPT-4.1-Mini responses within the AI chat interface for tasks like summarization and search.

```text
User: "Summarize my meeting notes from today"
GPT-4.1-Mini: Analyzes recent notes and provides a summary

User: "Find all notes about project X"
GPT-4.1-Mini: Searches vault and returns relevant results
```

--------------------------------

### Clone Repository and Navigate

Source: https://github.com/nexus-jpf/note-companion/blob/master/CONTRIBUTING.md

Clone the project repository and navigate into the project directory.

```bash
git clone https://github.com/Nexus-JPF/note-companion.git
cd note-companion
```

--------------------------------

### Key Development Commands

Source: https://github.com/nexus-jpf/note-companion/blob/master/ANALYSIS.md

Lists important commands for running the development server, building the plugin, linting, and testing.

```bash
- `pnpm next dev` - Development server (PORT=3010)
- `node esbuild.config.mjs` - Plugin development
- `pnpm test` - Run tests
- `pnpm next lint` - Code linting
```

--------------------------------

### Breaking API POST Request Example

Source: https://github.com/nexus-jpf/note-companion/blob/master/AGENTS.MD

This example demonstrates a breaking API change that will cause older plugins to fail. Avoid this pattern when updating API contracts.

```typescript
export async function POST(req: NextRequest) {
  const { newRequiredField } = await req.json();  // ❌ Old plugins will break
  // ...
```

--------------------------------

### Clean Monorepo Dependencies and Install

Source: https://github.com/nexus-jpf/note-companion/blob/master/REACT_HOOKS_ERROR_FIX.md

Command to clean all node_modules directories in the monorepo, remove lock files, and perform a fresh installation using pnpm. Useful for resolving complex dependency issues.

```bash
# From monorepo root
pnpm clean
rm -rf node_modules pnpm-lock.yaml
rm -rf packages/*/node_modules
pnpm install
```

--------------------------------

### Development Build Commands

Source: https://github.com/nexus-jpf/note-companion/blob/master/ANALYSIS.md

Provides essential commands for setting up dependencies and building the project packages.

```bash
pnpm i          # Install dependencies
pnpm build      # Build all packages
```

--------------------------------

### Configure Supabase Environment Variables

Source: https://github.com/nexus-jpf/note-companion/blob/master/packages/landing/README.md

After creating the app, rename the example environment file and insert your Supabase project URL and API anon key. These are found in your Supabase project's API settings.

```bash
cd name-of-new-app

rename .env.local.example to .env.local

NEXT_PUBLIC_SUPABASE_URL=[INSERT SUPABASE PROJECT URL]
NEXT_PUBLIC_SUPABASE_ANON_KEY=[INSERT SUPABASE PROJECT API ANON KEY]
```

--------------------------------

### Build and Run Docker Image

Source: https://github.com/nexus-jpf/note-companion/blob/master/SELF-HOSTING.md

Commands to build the Docker image and run it as a container, mapping the host port to the container port and using an environment file.

```bash
docker build -t note-companion .
docker run -p 3000:3000 --env-file packages/web/.env note-companion
```

--------------------------------

### Set Up Environment Variables for Self-Hosting

Source: https://github.com/nexus-jpf/note-companion/blob/master/SELF-HOSTING.md

Configure environment variables for self-hosting, including AI API keys and server settings. Ensure to create a .env file in the packages/web directory.

```env
# Required: At least one AI provider API key
OPENAI_API_KEY=sk-...your_key_here...

# Optional: Custom OpenAI-compatible API endpoint (for local LLMs like Ollama)
OPENAI_API_BASE=http://localhost:11434/v1  # Use this for local Ollama instances

# Optional: Additional AI providers
ANTHROPIC_API_KEY=sk-ant-...your_key_here...
GOOGLE_GENERATIVE_AI_API_KEY=...your_key_here...
GROQ_API_KEY=gsk_...your_key_here...
MISTRAL_API_KEY=...your_key_here...
DEEPSEEK_API_KEY=...your_key_here...

# Optional: AI Model Configuration (for self-hosting with custom providers)
# If not set, defaults to OpenAI with gpt-4o-mini (backward compatible)
MODEL_PROVIDER=openai  # Options: openai, anthropic, google, groq, mistral, deepseek
MODEL_NAME=gpt-4o-mini  # Model name for the selected provider
RESPONSES_MODEL_NAME=gpt-4o-mini  # Optional: Model for Responses API (OpenAI only, defaults to MODEL_NAME)

# Optional: Server configuration
PORT=3000  # Default is 3000 for production (3010 is used in development mode with `pnpm dev`)
NODE_ENV=production

# Optional: For OCR features (handwriting recognition)
GOOGLE_VISION_API_KEY=...your_key_here...

# Optional: User management (set to 'true' to enable, any other value or unset to disable)
ENABLE_USER_MANAGEMENT=false  # Disable for self-hosting without authentication
```

--------------------------------

### Build All Packages

Source: https://github.com/nexus-jpf/note-companion/blob/master/CONTRIBUTING.md

Compile and build all packages in the monorepo for production deployment.

```bash
pnpm build
```

--------------------------------

### Get Backlinks for a File (TypeScript)

Source: https://github.com/nexus-jpf/note-companion/blob/master/IMPLEMENTATION-LOCAL-TOOLS.md

Retrieves all files that link to a specified file. It distinguishes between resolved and unresolved backlinks.

```typescript
const getBacklinks = (filePath: string) => {
  const file = app.vault.getAbstractFileByPath(filePath);
  if (!(file instanceof TFile)) return [];
  
  const backlinks = app.metadataCache.getBacklinksForFile(file);
  return {
    resolved: Array.from(backlinks.keys()).map(path => ({
      path,
      count: backlinks.get(path),
    })),
    unresolved: Object.entries(app.metadataCache.unresolvedLinks)
      .filter(([, links]) => filePath in links)
      .map(([path, links]) => ({
        path,
        count: links[filePath],
      })),
  };
};
```

--------------------------------

### Monorepo Structure Overview

Source: https://github.com/nexus-jpf/note-companion/blob/master/ANALYSIS.md

Illustrates the directory structure of the monorepo, highlighting the different packages and their purposes.

```bash
packages/
├── web/           # Next.js web application
├── plugin/        # Obsidian plugin
├── shared/        # Shared utilities
└── release-notes/ # Release notes generator
```

--------------------------------

### Create a Feature Branch

Source: https://github.com/nexus-jpf/note-companion/blob/master/CONTRIBUTING.md

Start a new feature by creating a dedicated branch from the main repository. Use a descriptive name for your branch.

```git
git checkout -b feature/your-feature-name
```

--------------------------------

### Get Upload Status

Source: https://github.com/nexus-jpf/note-companion/blob/master/AGENTS.MD

Polls the status of an ongoing file upload or processing task. Use the fileId to check the status periodically.

```APIDOC
## GET /api/get-upload-status/{fileId}

### Description
Retrieves the current status of a file upload or processing task.

### Method
GET

### Endpoint
/api/get-upload-status/{fileId}

### Parameters
#### Path Parameters
- **fileId** (string) - Required - The unique identifier for the file whose status is being queried.
```

--------------------------------

### Basic File Organization Workflow

Source: https://github.com/nexus-jpf/note-companion/blob/master/docs/GPT-4.1-MINI-USAGE.md

Illustrates the automated file organization process using GPT-4.1-Mini. This involves dropping a file into an inbox and letting the system categorize it.

```text
1. Drop a file into your inbox folder
2. Note Companion uses GPT-4.1-Mini to analyze it
3. File is automatically moved to the appropriate folder
```

--------------------------------

### Web Dependencies (Current Server)

Source: https://github.com/nexus-jpf/note-companion/blob/master/BACKWARD_COMPATIBILITY_STRATEGY.md

Lists the current AI SDK dependencies on the server, showing it can be upgraded independently of plugins.

```json
{
  "@ai-sdk/openai": "^1.2.2",
  "@ai-sdk/anthropic": "^1.0.6",
  "@ai-sdk/google": "^1.1.20",
  "// ... other providers"
}
```

--------------------------------

### Configure Metro for Monorepo Dependencies

Source: https://github.com/nexus-jpf/note-companion/blob/master/REACT_HOOKS_ERROR_FIX.md

Configure Metro to prefer local dependencies in a monorepo setup. Ensure node_modules are correctly resolved.

```javascript
// metro.config.js template for React Native in monorepo
const path = require('path');

const config = getDefaultConfig(__dirname);

config.watchFolders = [__dirname];
config.resolver.nodeModulesPaths = [
  path.resolve(__dirname, 'node_modules'),
];
config.resolver.disableHierarchicalLookup = true;

module.exports = config;
```

--------------------------------

### Linux systemd Service Configuration

Source: https://github.com/nexus-jpf/note-companion/blob/master/SELF-HOSTING.md

Create this file to manage the Note Companion server as a systemd service on Linux. Ensure `your-username` and the `WorkingDirectory` are correctly set.

```ini
[Unit]
Description=Note Companion Server
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/note-companion/packages/web
ExecStart=/usr/bin/node .next/standalone/server.js
Restart=on-failure
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Build Application for Production

Source: https://github.com/nexus-jpf/note-companion/blob/master/REACT_HOOKS_ERROR_FIX.md

Build the application for both iOS and Android platforms to ensure the build process completes successfully without errors after the fixes.

```bash
# iOS
cd packages/mobile
pnpm build:ios

# Android
pnpm build:android

# Both should complete without errors
```

--------------------------------

### Configure Ollama for Local LLM Backend

Source: https://context7.com/nexus-jpf/note-companion/llms.txt

To use Ollama with Note Companion, first pull the desired model (e.g., llama3). Then, update `packages/web/.env` with the Ollama API key and base URL, and set the model provider and name.

```bash
# Use Ollama (local LLM) as the AI backend
ollama pull llama3
# In packages/web/.env:
# OPENAI_API_KEY="ollama"
# OPENAI_API_BASE="http://localhost:11434/v1"
# MODEL_PROVIDER=openai
# MODEL_NAME=llama3
```

--------------------------------

### Automatic Tool Result Handling

Source: https://github.com/nexus-jpf/note-companion/blob/master/AI_SDK_ELEMENTS_MIGRATION.md

Example of configuring `streamText` with tools, enabling automatic execution and result handling for a specified number of steps.

```typescript
// Automatic tool result handling
const result = streamText({
  model: openai('gpt-4o'),
  tools: {
    myTool: tool({
      description: "...",
      parameters: z.object({...}),
      execute: async (args) => {
        return { data: "result" };
      },
    }),
  },
  maxSteps: 5, // Auto-runs up to 5 tool calls
});
```

--------------------------------

### Verify Metro Resolution

Source: https://github.com/nexus-jpf/note-companion/blob/master/REACT_HOOKS_ERROR_FIX.md

Run the Expo start command with the --clear flag and observe the Metro bundler logs. Ensure that React is resolved exclusively from the mobile package's node_modules.

```bash
cd packages/mobile
npx expo start --clear

# Check Metro logs for React resolution
# Should only resolve to packages/mobile/node_modules/react
```

--------------------------------

### Button Usage Examples (React/TSX)

Source: https://github.com/nexus-jpf/note-companion/blob/master/ASSISTANT_STYLING_ANALYSIS.md

Demonstrates various ways to use the Button component, including different variants, sizes, icons, loading states, and custom styling. Ensure the necessary icon components are imported.

```tsx
// Primary button
<Button>Save Changes</Button>
```

```tsx
// Secondary with icon
<Button variant="secondary" leftIcon={<RefreshCw className="w-4 h-4" />}>
  Refresh
</Button>
```

```tsx
// Loading state
<Button isLoading>Processing...</Button>
```

```tsx
// Destructive action
<Button variant="destructive" size="sm">
  Delete
</Button>
```

```tsx
// Custom styling
<Button className="w-full">
  Full Width Button
</Button>
```

--------------------------------

### Client: Execute Search Tool with Obsidian API

Source: https://github.com/nexus-jpf/note-companion/blob/master/AGENTS.MD

Implement the execution logic for a specific tool, such as searching notes using the Obsidian API. This example shows how to access vault files and perform a basic text search.

```typescript
import React, { useRef } from "react";

export function SearchHandler({ toolInvocation, handleAddResult, app }) {
  const hasFetchedRef = useRef(false);

  const searchNotes = async (query: string) => {
    const files = app.vault.getMarkdownFiles();  // Obsidian API
    const searchTerms = query.toLowerCase().split(/\s+/);

```

--------------------------------

### Get Backlinks for a File in Obsidian

Source: https://github.com/nexus-jpf/note-companion/blob/master/IMPLEMENTATION-LOCAL-TOOLS.md

Retrieve all backlinks pointing to a specific file using `metadataCache.getBacklinksForFile(file)`. This shows which other notes link to the current file.

```typescript
metadataCache.getBacklinksForFile(file)
```

--------------------------------

### Configure Linux systemd Service

Source: https://context7.com/nexus-jpf/note-companion/llms.txt

Set up a systemd service file for persistent deployment of the Note Companion server on Linux. Ensure the `User` and `WorkingDirectory` are correctly set.

```ini
# Linux systemd service (optional persistent deployment)
# /etc/systemd/system/note-companion.service
[Unit]
Description=Note Companion Server
After=network.target

[Service]
Type=simple
User=notecompanion
WorkingDirectory=/opt/note-companion/packages/web
ExecStart=/usr/bin/node .next/standalone/server.js
Restart=on-failure
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Get All Unresolved Links in Obsidian

Source: https://github.com/nexus-jpf/note-companion/blob/master/IMPLEMENTATION-LOCAL-TOOLS.md

View a collection of unresolved (broken) links in the vault through `metadataCache.unresolvedLinks`. This helps in identifying and fixing broken internal references.

```typescript
metadataCache.unresolvedLinks
```

--------------------------------

### Using AI Tools with Max Steps

Source: https://github.com/nexus-jpf/note-companion/blob/master/AGENTS.MD

Illustrates how to use defined tools with an AI model, limiting the number of execution steps. It retrieves the generated text and all tool calls made during the process. Requires 'openai', 'tools', and 'generateText' to be set up.

```typescript
const { text, steps } = await generateText({
  model: openai('gpt-4o'),
  tools,
  maxSteps: 5,
  prompt: 'Analyze this data and calculate results',
});

// Access all tool calls
const allToolCalls = steps.flatMap(step => step.toolCalls);
```

--------------------------------

### Get All Markdown Files in Vault

Source: https://github.com/nexus-jpf/note-companion/blob/master/IMPLEMENTATION-LOCAL-TOOLS.md

Retrieve a list of all markdown files currently in the Obsidian vault using `vault.getMarkdownFiles()`. This returns an array of `TFile` objects.

```typescript
vault.getMarkdownFiles()
```

--------------------------------

### Check React Versions in Monorepo

Source: https://github.com/nexus-jpf/note-companion/blob/master/REACT_HOOKS_ERROR_FIX.md

Commands to check the installed React version in the mobile package and the root of the monorepo. Helps in quickly verifying dependency consistency.

```bash
# Mobile
cat packages/mobile/node_modules/react/package.json | grep version

# Root
cat node_modules/react/package.json | grep version 2>/dev/null || echo "No React in root"
```