# How to Manage Project Folders in ChocolateLMLite: A Complete Developer Guide

> Learn to manage project folders in ChocolateLMLite. Discover how the FileManager class safely creates reads and enumerates workspace files in isolated data directories.

- Repository: [Segment (gpsnmeajp)/chocolatelmlite](https://github.com/gpsnmeajp/chocolatelmlite)
- Tags: how-to-guide
- Published: 2026-03-02

---

**ChocolateLMLite stores persona-specific project files in isolated `data/persona_<id>/project/` directories and provides the `FileManager` class with built-in path traversal protection to safely create, read, and enumerate workspace files.**

Managing project folders in ChocolateLMLite is essential for organizing persona-specific assets and source code. The repository implements a secure, sandboxed file system through the `FileManager` class in [`src/FileManager.cs`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/src/FileManager.cs), ensuring that each persona's project files remain isolated and protected from directory traversal attacks. This guide covers the architecture, security mechanisms, and API methods for programmatically managing project folders.

## Understanding the Project Folder Architecture

### Directory Structure and Storage Location

Every persona in ChocolateLMLite receives a dedicated workspace under the `data` directory. When you create a new persona using `CreateNewPersona`, the system automatically generates a `project` subfolder:

- **Root path**: `data/persona_<id>/`
- **Project workspace**: `data/persona_<id>/project/`

This structure ensures that files belonging to different personas never intersect, maintaining strict data isolation between workspaces.

### Security Boundaries and Path Traversal Protection

The `FileManager` class implements multiple security layers to prevent unauthorized file access. According to the source code in [`src/FileManager.cs`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/src/FileManager.cs) (lines 1236-1242), the system validates that any target file's absolute path must start with the persona's project directory absolute path.

Key security features include:

- **Path sanitization**: The `SanitizeFilename` method strips illegal characters from filenames to prevent injection attacks.
- **Directory traversal blocking**: Attempts to access paths like [`../secret.txt`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/../secret.txt) raise an `InvalidOperationException`.
- **Automatic folder creation**: If the `project` directory is missing, the system creates it on demand during write operations.

## Creating and Accessing Project Folders Programmatically

### Initializing a New Persona Workspace

To create a project folder, you first create a persona. The `CreateNewPersona` method in [`FileManager.cs`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/FileManager.cs) handles both the persona record and the directory structure.

```csharp
using ChocolateLMLite;

// Initialize the file manager
var fm = new FileManager();

// Create a new persona - this automatically creates the project folder
string? newId = fm.CreateNewPersona("DemoPersona");
// Returns: persona_1234567890 (timestamp-based ID)
// Creates: data/persona_1234567890/project/

```

### Writing and Reading Project Files

Once the workspace exists, use `SaveProjectFileContentToActivePersona` to write files and `GetProjectFileContentFromActivePersona` to retrieve them. These methods automatically handle path sanitization and security checks.

```csharp
// Save a JavaScript file to the project
string filename = "app.js";
string code = @"console.log('Hello, Chocolate LMLite!');";

// This writes to: data/persona_<id>/project/app.js
fm.SaveProjectFileContentToActivePersona(filename, code);

// Retrieve the file content later
string retrieved = fm.GetProjectFileContentFromActivePersona(filename);
Console.WriteLine(retrieved); 
// Output: console.log('Hello, Chocolate LMLite!');

```

### Listing and Managing Project Files

To enumerate all files in the project directory, use `GetProjectFileListFromActivePersona`. This returns a list of filenames currently stored in the workspace.

```csharp
// Get all files in the project folder
List<string> files = fm.GetProjectFileListFromActivePersona();

// Example output: ["app.js", "README.md", "styles.css"]
Console.WriteLine(string.Join(", ", files));

```

## Integrating Project Files with LLM System Prompts

ChocolateLMLite extends the LLM context by injecting project file metadata into system prompts. When `generalSettings.EnableProject` is set to `true`, the `SystemPrompt.BuildSystemPrompt` method in [`src/SystemPrompt.cs`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/src/SystemPrompt.cs) automatically reads the project file list and includes it as `<project_files>` XML tags.

This integration allows the language model to reference the current workspace structure without manual configuration. The file list is generated using the same `GetProjectFileListFromActivePersona` method, ensuring consistency between the file system and the AI context.

## Summary

Managing project folders in ChocolateLMLite involves understanding the sandboxed directory structure and utilizing the `FileManager` API for secure file operations:

- **Storage location**: Project files reside in `data/persona_<id>/project/`, created automatically when a persona is initialized via `CreateNewPersona`.
- **Security model**: The system enforces path traversal protection and filename sanitization through [`src/FileManager.cs`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/src/FileManager.cs), rejecting attempts to access files outside the designated workspace.
- **Core operations**: Use `SaveProjectFileContentToActivePersona` and `GetProjectFileContentFromActivePersona` for file I/O, and `GetProjectFileListFromActivePersona` for directory enumeration.
- **LLM integration**: Enable `generalSettings.EnableProject` to automatically inject file lists into system prompts via `SystemPrompt.BuildSystemPrompt`.

## Frequently Asked Questions

### Where are project folders stored in ChocolateLMLite?

Project folders are stored within persona-specific directories under the `data` folder. Each persona receives a workspace at `data/persona_<id>/project/`, where `<id>` is the timestamp-based identifier generated during persona creation. This structure ensures complete isolation between different personas.

### How do I prevent path traversal attacks when saving files?

ChocolateLMLite automatically prevents path traversal attacks through the `FileManager` class in [`src/FileManager.cs`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/src/FileManager.cs). The system validates that any target file's absolute path must begin with the persona's project directory absolute path. Attempts to use directory traversal sequences like `../` in filenames will raise an `InvalidOperationException`.

### Can I use project files with the LLM system prompt?

Yes. When you set `generalSettings.EnableProject` to `true` in the settings, the `SystemPrompt.BuildSystemPrompt` method automatically scans the project folder and injects a list of available files into the LLM context using `<project_files>` XML tags. This allows the language model to reference your codebase without manual copy-pasting.

### What happens if the project folder doesn't exist?

If the project folder is missing, ChocolateLMLite creates it automatically on demand. When you call methods like `SaveProjectFileContentToActivePersona` or `GetProjectFileListFromActivePersona`, the `FileManager` checks for the directory existence and initializes it if necessary. This ensures that file operations never fail due to missing directories.