# Deep Wiki

### Opening Deep Wiki

You can hover over a function/class → get an option **Open in Deep Wiki** and It generates very rich, structured documentation with proper sections.

<figure><img src="/files/deQmZqcfgEogZy0YRKtU" alt=""><figcaption></figcaption></figure>

***

### What Deep Wiki generates

For each target, C0 produces a structured documentation entry with the following sections:

#### Overview

A plain-language description of what the code does its purpose and responsibility, written for a developer who hasn't read the implementation.

#### Signature

The function or class signature, including parameter types, return type, and thrown exceptions.

#### When to use it

This is what separates Deep Wiki from a docstring generator. C0 reads how the code is actually used across your codebase and writes guidance for when it's the right tool and when it isn't.

```
Use OrderService.create() when creating an order from a user-facing flow (checkout,
subscription renewal, admin order entry). Don't use it for programmatic test data
setup use OrderFactory from tests/support/factories.ts instead, which skips
payment processing and email sending.
```

#### Parameters

Each parameter documented with its type, purpose, acceptable values, and what happens with edge cases (null, empty, zero, maximum values).

#### Return value

What the function returns, what the shape of the data looks like, and what to check for before using it.

#### Throws / error cases

Every exception or error condition the function can produce, what triggers it, and how callers should handle it.

#### Best-case usage notes

Practical guidance on how to use the code well the patterns that work, the ones that don't, and the things experienced developers know that aren't obvious from the signature alone.

```
Best results: call recalculateTotals() after any mutation to the order's line items.
If you're making multiple mutations, batch them and call recalculateTotals() once at
the end — it's expensive and doesn't need to run after each change.
```

#### Known edge cases

Specific inputs or conditions that produce behavior worth knowing about things that aren't bugs but aren't immediately obvious.

```
Edge cases:
- If quantity is 0, the item is removed from the order rather than kept with a zero quantity.
- If all items are removed, the order is cancelled automatically, not left as an empty order.
- Applying a discount code that's already applied is a no-op, not an error.
```

#### Related functions

Functions and classes that work closely with this one either called by it, calling it, or used alongside it.

***

### Examples

**A service method:**

```
Input: @SessionManager.refresh  "Generate a Deep Wiki entry."

Output:

## SessionManager.refresh(sessionId: string, userId: number): Promise<Session>

### Overview
Refreshes an existing session, extending its TTL and returning the updated Session
object. Called automatically by the auth middleware on authenticated requests.

### When to use it
Use this when you need to explicitly extend a session outside of a normal request
cycle — for example, during a long-running background job initiated by a user action.
Don't call this directly in request handlers; the middleware handles it automatically
for all authenticated routes.

### Parameters
- sessionId — the session token string from the user's cookie or Authorization header.
  Must be a valid session that exists in Redis. Throws SessionNotFoundError if absent.
- userId — the ID of the user the session belongs to. Used to verify the session
  belongs to the correct user before refreshing. Throws SessionMismatchError if it
  doesn't match.

### Returns
The updated Session object with the new expiresAt timestamp.

### Throws
- SessionNotFoundError — the sessionId doesn't exist in Redis (expired or never existed)
- SessionMismatchError — the session exists but belongs to a different userId
- StorageError — Redis is unavailable

### Best-case usage notes
The TTL on refresh is controlled by SESSION_TTL_SECONDS in config/auth.ts.
If you need to refresh with a non-standard TTL (e.g., "remember me" sessions),
use SessionManager.refreshWithTTL() instead.

### Known edge cases
- Calling refresh on a session that expires within the next 5 seconds may result in
  a SessionNotFoundError, because Redis may have already evicted it by the time the
  write completes.
- If Redis is in readonly mode during a failover, refresh will throw StorageError
  but the auth middleware will still allow the request to proceed (fail-open behavior).

### Related
- SessionManager.create() — creates a new session
- SessionManager.invalidate() — terminates a session
- AuthMiddleware.verify() — the main caller in request flows
```

***

### Generating wiki entries for modules

Deep Wiki works at the module level too, not just individual functions. Point it at a directory or a group of related files and it generates an overview document for the whole module:

```
@src/services/  "Generate a Deep Wiki overview of the services layer."
```

The module-level entry covers: what the module is responsible for, what it isn't responsible for, how it's organized, what external dependencies it takes on, and how to navigate it.

***

### Keeping documentation current

Deep Wiki entries are stored in your project (by default in a `docs/wiki/` directory, configurable in settings). As your codebase changes, C0 detects when an indexed function has changed significantly and flags the corresponding wiki entry as potentially stale.

You can re-generate a wiki entry at any time, or configure C0 to automatically update wiki entries when the underlying code changes.

***

### Tips

**Generate wiki entries for the hardest parts of your codebase first.** Every team has functions that every engineer has to re-read every time they touch them. Generate Deep Wiki entries for those immediately the ROI is highest where understanding is most expensive.

**Use Deep Wiki during onboarding.** When a new team member joins, point them at the Deep Wiki entries for the core services and workflows. A good set of entries turns a month of context-building into a week.

**Include "when NOT to use" guidance.** The most valuable documentation often explains what not to do. When C0 generates a wiki entry, read the "when to use it" section and add notes for the anti-patterns you've seen calls you've had to revert, mistakes that come up in code review. C0 generates from the code; you add from experience.

**Use it after debugging.** When you've just finished debugging a gnarly issue in a function, generate a Deep Wiki entry immediately. You understand that code better in that moment than you will for a while. That understanding ends up in the entry.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.codemate.ai/c0/deep-wiki.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.