Build the handbook
Project structure
Find the content, website code, settings, and instructions for your coding agent.
Open the complete company-knowledge-base folder in your editor. This is the project root. The folders inside separate the content people read from the code that displays it and the tools that run the project.
Use this page as a map. You do not need to read every file before making your first change. The Sanity and chat code is already included, but you do not need to configure those features to browse the local handbook.
Explore the tree
This tree shows the main files in the complete example, rather than the plain Fumadocs starter. Each row explains what that folder or file does. Expand a folder to look inside.
The tree includes one policy and one employee as examples. The repository has the other departments, people, and supporting scripts too.
What folders do
| Folder | Why it exists |
|---|---|
app/ | Website pages, shared layouts, styles, and server endpoints. Its folders help determine the URLs. |
components/ | Reusable interface pieces, such as the logo, search overlay, and chat panel. |
content/ | Markdown policies and employee JSON records used in local mode and for the initial Sanity import. |
lib/ | Shared logic for loading content, building the sidebar, searching, and checking access. |
public/ | Static assets served by the website, including employee avatars. |
sanity/ | The document definitions for policies and employees. These determine the fields available in Studio. |
scripts/ | Commands you run for tasks such as creating the Sanity dataset and importing content. |
tests/ | Automated checks for content, links, access, and chat behavior. |
docs/ | Notes about this repository, including the recording guide. The handbook's policy content lives in content/docs/. |
The extension tells you what a file contains. .md is Markdown text, .json is structured data, and .css controls appearance. .ts is TypeScript code, .tsx can also describe React interfaces, and .mjs is JavaScript code using modules.
Instructions and settings
README.md is the starting guide for someone opening the repository. It explains how to install, configure, and run the app.
AGENTS.md gives a coding agent project-specific instructions. Ours asks it to read the README, keep the demo small, protect credentials, and run checks after code changes. It is a text document, not website code or an AI feature visitors use. You can adapt these instructions for your project; in this repository, CLAUDE.md points Claude Code to the same file.
| File | What it controls |
|---|---|
package.json | The required packages and named commands. For example, npm run dev runs the dev command defined here. |
package-lock.json | The resolved package versions, so installs can use the same dependency versions. npm maintains this file. |
.env.example | A shareable template listing the settings the app expects. |
.env | Your local settings, including content mode and API keys. You create it during setup; keep its values private. |
.gitignore | Tells Git which untracked files to leave out, including .env and generated folders. |
proxy.ts | Checks the shared-password session before allowing access to protected pages and endpoints. |
next.config.mjs | Settings for Next.js, which runs and builds the website. |
tsconfig.json | TypeScript settings for checking code. |
postcss.config.mjs | Connects Tailwind to the stylesheet build. |
sanity.config.ts and sanity.cli.ts | Configure the Sanity Studio editor and its command-line tools. |
After installing and running the app, you will also see node_modules/ and .next/. These contain downloaded packages and generated build files. Edit the source files above; let the tools maintain these folders and the generated next-env.d.ts file.
Find an element
| What you want to change | Where to start |
|---|---|
| Homepage headline and sections | app/page.tsx |
| Department names, icons, and descriptions | lib/company.ts |
| Policy text and metadata in local mode | content/docs/<department>/<page>.md |
| Sidebar hierarchy and page order | lib/content.ts, using each policy's department and order |
| Sidebar shell and footer controls | app/docs/layout.tsx |
| Page title, owner link, and rendered body | app/docs/[[...slug]]/page.tsx |
| Employee records and team directory | content/employees/*.json and app/docs/team/page.tsx |
| Colors, fonts, and spacing | app/global.css |
| Search interface and retrieval | components/search.tsx and lib/retrieval.ts |
| Chat panel and answer generation | components/chat.tsx and app/api/chat/route.ts |
In Sanity mode, edit policy and employee content in Studio. The website still uses these same layout and interface files.
From file to page
For /docs/operations/travel-expenses, the local content starts in content/docs/operations/travel-expenses.md. lib/local-content.mjs reads its metadata and body. lib/content.ts groups the pages and builds the sidebar for Fumadocs.
In app/, a page.tsx file displays a page and a layout.tsx wraps pages in a shared shell. A route.ts handles a server request, such as a search, rather than displaying a page.
The unusual folder name [[...slug]] lets one page template handle different paths under /docs. It looks up the requested policy or employee profile and displays it inside the docs layout. You do not need a separate React file for every policy.
Checkpoint
Find AGENTS.md, the homepage, and Travel expenses in your editor. Ask your coding assistant to explain those files before changing anything.
Read AGENTS.md and README.md. Give me a short tour of this repository.
Show me which files control the homepage, a policy, and the sidebar.
Explain unfamiliar terms and do not change any files yet.Next, understand the layout and make a small change to the handbook.