This is the full developer documentation for Falconer # Quickstart > Connect your first source to Falconer and ask questions or write a doc about your codebase. Connect your first source to Falconer and ask questions or write a doc about your codebase. In this quickstart, you will: - Connect GitHub to Falconer - Ingest your code - Ask your first question - Create your first document ## Step 1: Connect GitHub Connect your GitHub repo to index your code. 1. Navigate to **Integrations** from the bottom left menu. 2. Next to GitHub, click **Connect.** 3. Authorize Falconer to access your repositories (you can also add a public repo). 4. Select which repositories you want to connect. Falconer ingests your code as context within minutes, so you can immediately start asking questions and writing docs. ## Step 2: Ask your first question Ask questions about your codebase from the home page. Falconer uses your code and other connected sources to deliver high-quality answers with citations.  ## Step 3: Write a doc for the answer In the prompt box, say "Write a doc for this." Falconer will take the context and convert it into a document.  ## Next steps - [**Connect more sources**](/docs/set-up/connect-sources) -- Add Slack, Linear, Notion, and more to give Falconer broader context across your stack. - [**Write a doc from Slack**](/docs/write/write-a-doc-from-slack) -- Turn any Slack thread into a structured Falconer document in one step. - [**Update docs from Slack**](/docs/update/update-docs-from-slack) -- Keep docs current by asking Falcon to apply updates directly from a conversation. - [**Capture decisions in Slack**](/docs/ask/capture-decisions-in-slack) -- Use `@Falcon remember` to save important decisions and context the moment they happen. # Generate docs automatically > Falconer Generate creates a complete set of documentation from your codebase -- so you're not starting from a blank page. Falconer Generate creates a complete set of documentation from your codebase -- so you're not starting from a blank page. Connect a GitHub repo, define the folder and doc structure you want, and Falconer writes every page for you in the background. ## Prerequisites - A connected GitHub repository (go to **Settings -> Sources** to connect one) - Starter plan (1 doc set) or Pro plan (multiple doc sets) ## Start Generate There are two ways to kick off generation: - **Quick setup** -- during onboarding, after you connect a GitHub repo, Falconer offers a one-click option to generate a default doc set. Select a repository and click **Generate**. This creates five starter docs (Project overview, Get started, Architecture overview, Contributing guide, and Glossary) inside an Engineering folder. - **Generate** -- right-click **Company documents** in the left sidebar and choose **Generate documentation**. This opens the full dialog where you can customize the folder structure before generating. ## Build the doc tree The Generate modal opens with a suggested folder and doc structure. You can customize it before generating: - **Select a repository** -- use the dropdown in the top-right corner to choose which connected repo Falconer should read from. A green dot means the repo is fully indexed; an orange pulsing dot means indexing is still in progress. - **Add folders** -- click **Add folder** to create a new top-level folder, or use the folder menu to nest a subfolder. - **Add docs** -- inside any folder, add a document. Give it a **title** (required) and an optional **description** that tells Falconer what the doc should cover. - **Rename or delete** -- click any folder or doc name to edit it. Delete items you don't need. The modal footer shows a running count of documents against the per-generation limit. Every folder must contain at least one document, and every document needs a title. ### Default doc set If you don't customize, Falconer starts with these five docs under an **Engineering** folder: | Document | Description | | --- | --- | | **Project overview** | What the project does, why it exists, and who it's for | | **Get started** | Step-by-step setup: prerequisites, installation, environment config, first local run | | **Architecture overview** | System structure, major components, data flow, tech stack, key design decisions | | **Contributing guide** | Contributor workflow, PR expectations, branching conventions, coding standards | | **Glossary** | Domain-specific terms, acronyms, and project jargon | You can add, remove, or rename any of these before generating. ## Generate Click **Generate** to start. Falconer verifies the repository is indexed, then generates each document in the background by inspecting your actual codebase with code search. A progress overlay tracks how many docs have been created. Once generation completes, the new docs appear in your sidebar under the folder structure you defined. ## FAQ **Is this for onboarding or can I use this to generate any doc set?** Both. This is a great way to start with a high-quality doc set with nothing but a codebase. It's also great when you create a new service, feature, or product and want to generate docs for it. **Can I customize the auto-generated docs?** Yes, in a couple of ways. You can define the docs structure before generating the docs. And you can edit them after they're published. # How Falconer works > Falconer is a knowledge platform for engineering teams. It connects to the tools your team already uses, builds a unified knowledge base from them, and gives you an AI agent -- Falcon -- to search, write, and keep documentation up to date. Falconer is a knowledge platform for engineering teams. It connects to the tools your team already uses, builds a unified knowledge base from them, and gives you an AI agent -- Falcon -- to search, write, and keep documentation up to date. ## Connect, understand, and act Falconer works in three stages: connect, understand, and act. ### 1. Connect your sources Falconer connects to the tools where your team already works: - **GitHub**: code repositories, pull requests, and commit history - **Slack**: recent messages from a named public channel that Falcon has joined, searched on demand - **Linear**: tasks, issues, and project status - **Notion, Google Docs, and Confluence**: existing documentation Once [connected](/docs/set-up/connect-sources), Falconer continuously indexes synced sources and accesses live sources on demand so its knowledge stays current as your codebase and team evolve. ### 2. Build a unified knowledge base Falconer processes ingested content into a searchable knowledge base using a hybrid approach: - **Semantic search** understands the meaning behind a query, not just keywords - **Full-text search** handles exact matches across documents, code, and tasks - **A knowledge graph** maps relationships between documents, code, people, and entities Together, these three layers let Falconer answer questions like *"What does the payment service do and who owns it?"* by reasoning across sources. ### 3. Act through Falcon Falcon is the AI agent that sits on top of the knowledge base. It can: - [**Answer questions**](/docs/ask/ask-questions-in-slack): search relevant connected sources and return cited answers - [**Write documentation**](/docs/write/write-a-doc): generate docs grounded in your actual code, tasks, and existing docs - [**Keep docs up to date**](/docs/update/keep-docs-in-sync-with-prs): when a PR merges, Falcon detects which documents are affected and proposes updates for your review - [**Work where you are**](/docs/update/update-docs-from-slack): available in the Falconer editor (type **/** anywhere), on the homepage, and directly in Slack (`@Falcon`) Every response includes citations so you can verify where the information came from. ## Documents in Falconer Falconer has its own document editor for writing and publishing documentation. Start from scratch or let Falcon draft a document based on your connected sources. Documents are organized into collections: either private (visible only to you) or company-wide (searchable by your whole team). ## The self-updating loop The core idea behind Falconer is that documentation should stay in sync with your codebase automatically. When code changes, Falconer detects which docs are affected and Falcon drafts proposed updates, then notifies the document owner to accept, review, or reject them -- keeping your knowledge base accurate without manual effort. # Falconer docs > Falconer is a self-updating knowledge platform that provides humans and agents with a long-term memory system. # Ask questions in Slack > Ask Falcon questions directly in Slack to get instant answers from your knowledge base -- without leaving your conversation. Ask Falcon questions directly in Slack to get instant answers from your knowledge base -- without leaving your conversation. ## Prerequisite Ensure [Slack is connected](/docs/set-up/connect-sources) to your Falconer org. ## Add Falcon to a channel Mention `@Falcon` in any channel where the bot is present to ask questions. Falcon responds with answers grounded in your knowledge base, including citations to source materials. You can also DM with Falcon or add it to a group DM. ## Ask questions Mention `@Falcon` followed by your question. Falcon searches your connected documents, code repositories, and Linear tasks to provide accurate answers with citations. To search Slack, name a public channel that Falcon has joined; Falcon checks that channel's recent messages on demand.  **Example questions:** ``` @Falcon How does authentication work in our API? ``` ``` @Falcon What's the deployment process for staging? ``` ``` @Falcon Who owns the marketing site? ``` Falcon provides real-time responses with citations to specific files, documents, or conversations so you can verify the information and explore further. ## Permissions Falcon respects your organization's permissions. Users only see answers based on documents and resources they have access to in Falconer. # Capture decisions in Slack > Important decisions happen in Slack, then vanish. Use @Falcon remember to save any fact, decision, or context the moment it happens, right from Slack. Important decisions happen in Slack, then vanish. The team agrees on a design approach, someone shares a workaround, and a week later no one can find any of it. Use `@Falcon remember` to save any fact, decision, or context *the moment it happens*, right from Slack. Falcon stores this information as searchable memory, ready to surface when answering questions or writing docs.  ## Ask Falcon to remember things In any Slack channel, thread, or DM, type `@Falcon remember` to save any fact worth keeping. It can read through long threads instantly to find what you want to save. Use it to remember things like workarounds, architecture decisions, and meeting outcomes. Falcon confirms creating the memory in a thread. If a conflicting memory already exists, Falcon asks whether you want to replace it before storing the new fact -- keeping you in control of what gets remembered. **Examples:**   ## What Falcon does with memories Once a memory is saved, Falcon treats it as a high-trust source, the same way it treats your documents and code. When someone asks a related question in Slack, Falcon surfaces the memory with full provenance: who captured it, when, and where.  ## Next steps Try it: Type `@Falcon remember [a recent team decision]` in any channel. # Falconer vs AI chatbots > Falconer and general-purpose AI assistants like Claude or ChatGPT are complementary tools. Here's how to think about when to use each. Falconer and general-purpose AI assistants like Claude or ChatGPT are complementary tools. Here's how to think about when to use each. ## Use Falconer for company knowledge Falconer is purpose-built for your organization. It has full context on your docs, tasks, code, and teammates -- so you get better answers without having to explain background every time. **Use Falconer to:** - Ask questions about your company's docs, code, or processes - Reference specific teammates, tasks, or files in your answer - Write or update internal documentation - Turn a conversation into a shareable doc in one click > **Note:** When the question is about your company, Falconer will provide answers using your context, even with shorter prompts. ## Use an AI chatbot Tools like Claude or ChatGPT are well suited for tasks that go beyond your company's knowledge base. **Use them for:** - More up-to-date information from the internet - Memory across many past conversations - Broad, open-ended tasks that don't depend on internal context # Find answers with Falconer > Use Falconer to instantly find answers across your codebase, docs, and tasks. Use Falconer to instantly find answers across your codebase, docs, and tasks. ## Where to ask questions ### From the homepage Go to the [Falconer homepage](https://falconer.com/home) and use the search bar to ask questions about your knowledge base. Falconer searches connected sources such as GitHub repositories, Linear tasks, Notion pages, and Google Drive to deliver the best answer. Slack is searched on demand only when you name a public channel that Falcon has joined. ### From the editor While working in a document, open the right sidebar and chat with the Falcon agent.  Every answer cites sources from your organization, so your team knows the information is current. ### From Slack [Ask Falcon questions directly in Slack](/docs/ask/ask-questions-in-slack). ## What to ask Falcon searches the sources relevant to your question and gives a single answer. Here are some examples: Parts of your codebase: ``` How does authentication work end-to-end? ``` The status of tasks and projects: ``` What's the current status of the billing refactor? ``` Decisions and context: ``` Why did we switch from Redis to Postgres for session storage? ``` Processes and policies: ``` What's the deployment process for staging? ``` ## Next steps After receiving an answer, you can use Falconer to [write a document](/docs/write/write-a-doc). # Personalize the agent > Tailor every Falconer answer to your role, team, and preferences with Agent Personalization. Agent Personalization tailors every response Falconer gives you. The agent builds a lightweight profile of who you are -- your role, your team, the systems you own, the projects you care about, and how you like answers formatted -- and uses it to skip context you already know. ## Where to find it Go to **Settings → Personal settings → Personalizations → Agent personalization** to see your profile.  Every attribute the agent knows about you is listed on a single page. Filter by "added by you" vs. "auto-detected," search across attributes, edit any one inline, or delete what you don't want Falconer to use. ## How attributes get added Attributes come from two sources. ### Attributes you add Write attributes directly in your profile -- your role, your team, and personal preferences. For example: ``` I prefer bullet points over tables. ``` ``` I own the billing service and the payments pipeline. ``` Add a role and team, or write a freeform attribute up to 500 characters. ### Auto-detected attributes Falconer extracts durable, identity-level attributes from your Slack and in-app conversations as you use the product. Each one is traced back to its source so you can verify it. The agent only extracts attributes that describe _you_ -- not one-off questions or transient context. ## Editing and removing attributes Your profile is editable end-to-end: - **Edit any auto-detected attribute** -- once you do, it's marked "Edited by you" and Falconer trusts your version. - **Delete anything** you'd rather Falconer forget. - **Add freeform attributes** any time you want the agent to know something new. ## What to add to your profile Some examples of useful attributes: Your role and ownership area: ``` Backend engineer on the platform team. I own auth and session management. ``` How you like answers formatted: ``` Prefer short answers with code examples. No long prose. ``` Projects or systems you care about: ``` Currently leading the migration from Redis to Postgres for sessions. ``` ## Next steps After setting up your profile, [ask Falconer a question](/docs/ask/find-answers-with-falconer) and the agent will tailor its answer to you. # Use voice mode > Use voice mode to speak your prompts instead of typing them. Try it when you want to draft docs hands-free or describe something faster than you can type it. Use voice mode to speak your prompts instead of typing them. Try it when you want to draft docs hands-free or describe something faster than you can type it. ## Prerequisites The first time you use voice mode, your browser will ask for microphone access. Click **Allow** -- recording won't work without it. > **Note:** Voice mode is available on **Falconer Pro plans**. If you don't see the microphone icon, check that your organization has an active Pro subscription. ## Record a prompt 1. Open Falconer and go to the prompt box -- on the homepage or on the sidebar of any document. 2. Click the **microphone icon** to start recording. 3. Speak your prompt at a natural pace. 4. Click the **stop icon** when you're done. 5. Review the transcribed text in the prompt box, then submit as normal. # Integrations > Connect the tools your team already uses so Falconer can search, write, and keep documentation up to date across your stack. Connect the tools your team already uses so Falconer can search, write, and keep documentation up to date across your stack. Each integration takes a few clicks to set up. For the general connection flow, prerequisites, and what each button means, see [Connect sources](/docs/set-up/connect-sources). ## Available integrations | Integration | What it brings to Falconer | | --- | --- | | [Slack](/docs/integrations/slack) | Ask questions and manage docs directly from Slack. | | [GitHub](/docs/integrations/github) | Connect repositories to ask about your codebase. | | [Linear](/docs/integrations/linear) | Sync issues and projects for context-aware answers. | | [Notion](/docs/integrations/notion) | Import pages and databases from your workspace. | | [Confluence](/docs/integrations/confluence) | Sync documentation from your Confluence spaces. | | [Google Drive](/docs/integrations/google-drive) | Connect your personal Google Drive files. | | [Google Workspace](/docs/integrations/google-workspace) | Sync documents across your Google Workspace. | | [Gmail](/docs/integrations/gmail) | Import emails and threads from Gmail. | | [Zendesk](/docs/integrations/zendesk) | Import help center and support articles. | | [Granola](/docs/integrations/granola) | Sync meeting notes and transcripts. | See which integrations are available for your plan on the [pricing page](https://falconer.com/pricing). # Confluence > Sync documentation from your Confluence spaces. Connect Confluence so the documentation your team has built up over the years becomes searchable alongside your code, tasks, and conversations. ## What's synced Pages from the Confluence spaces you select. ## What you can do - Search across all of your connected Confluence spaces. - Ask Falcon about documentation and runbooks. - Keep Confluence content in sync so you find the latest version, not stale links. ## Connect Confluence 1. Navigate to **Integrations** from the bottom-left menu. 2. Click **Connect** next to Confluence. 3. Authorize Falconer to access your Confluence account. 4. Select which spaces to sync. Use **Configure** at any time to change which spaces are synced. Confluence is available on Custom plans. Contact [support@falconer.com](mailto:support@falconer.com) to learn more. # GitHub > Connect repositories to ask about your codebase. Connect GitHub and start asking questions and writing docs about your codebase in minutes. It's the fastest way to give Falconer real context about how your software works. ## What's synced Repositories, code files, and pull requests from the repositories you select. ## What you can do - Ask questions about your codebase and get code-aware answers. - Generate documentation directly from code. - [Detect when code changes affect documentation.](/docs/update/keep-docs-in-sync-with-prs) ## Connect GitHub 1. Navigate to **Integrations** from the bottom-left menu. 2. Click **Connect** next to GitHub. 3. Authorize Falconer to access your GitHub account. 4. Select the specific repositories you want to sync. Falconer begins syncing immediately. Initial indexing typically completes within minutes. Connecting GitHub requires GitHub organization admin permission and owner permission to your Falconer organization. Use **Configure** at any time to change which repositories are synced. ## Public repositories You can also add public repositories without authentication. Use the public repository option on the Integrations page to index any public repo by URL. # Gmail > Connect Gmail to search your inbox live with Falconer. Connect Gmail so the decisions and context buried in your inbox become reachable when you ask Falcon a question. ## How it works Gmail is a live connection, not a synced source. Falconer doesn't index or store your email. When a question needs it, Falcon searches your inbox in real time through your connected account. ## What you can do - Search emails and threads across your inbox. - Ask Falcon to summarize long email threads. ## Connect Gmail 1. Navigate to **Integrations** from the bottom-left menu. 2. Open the **Personal** tab. 3. Click **Connect** next to Gmail and authorize Falconer to access your account. Gmail is a personal connection, so each teammate connects their own account. # Google Drive > Connect your personal Google Drive files. Connect Google Drive so the documents, sheets, and slides your team works in become part of Falconer's knowledge. ## What's synced Files from your Google Drive, respecting Drive's sharing and access permissions. ## What you can do - Search documents, sheets, and slides in Drive. - Ask Falcon about the contents of any file. - Keep Drive files indexed and up to date. ## Connection methods Google Drive offers three ways to connect: 1. **Personal connection** -- Connect your individual Google account. Falconer can access docs you've created or opened. 2. **Workspace connection** -- A Google Workspace admin connects the entire organization. This provides broader access but requires additional configuration in Google Cloud Console. See [Google Workspace](/docs/integrations/google-workspace). 3. **Invite Falconer to your drive** -- Get more granular control by sharing specific files or folders with a Falconer email address. ## Connect Google Drive 1. Navigate to **Integrations** from the bottom-left menu. 2. Click **Connect** next to Google Drive and choose your connection method. 3. Follow the authorization steps, or for the targeted connection, use **Instructions** to view step-by-step setup. Google Drive is available on Custom plans. Contact [support@falconer.com](mailto:support@falconer.com) to learn more. # Google Workspace > Sync documents across your Google Workspace. Connect Google Workspace to bring organization-wide knowledge into Falconer in a single setup, instead of connecting accounts one at a time. ## What's synced Documents across your Google Workspace, honoring Workspace permissions and sharing rules. ## What you can do - Search across your entire Google Workspace. - Ask Falcon questions across teams and shared drives. - Keep org-wide knowledge continuously in sync. ## Connect Google Workspace 1. A Google Workspace admin connects the entire organization from the **Integrations** page. 2. Complete the required configuration in Google Cloud Console. 3. Authorize Falconer to access your Workspace. This provides broader access than a personal [Google Drive](/docs/integrations/google-drive) connection but requires admin setup. Google Workspace is available on Custom plans. Contact [support@falconer.com](mailto:support@falconer.com) to learn more. # Granola > Sync meeting notes and transcripts. Connect Granola so what was decided in your meetings becomes searchable, durable knowledge instead of notes nobody reopens. ## What's synced Meeting notes and transcripts. ## What you can do - Search meeting notes and transcripts. - Ask Falcon what was decided in any meeting. - Keep meeting notes in sync with your docs. See [Sync Granola meeting notes](/docs/use-cases/automate-workflows/sync-granola-meeting-notes) for a full walkthrough. ## Connect Granola 1. In Granola, go to **Settings → Connectors → API keys** and generate a key with the **Personal** scope. Optionally add the **Public** scope to include team-shared notes. 2. In Falconer, navigate to **Integrations** from the bottom-left menu and open the **Personal** tab. 3. Click **Connect** next to Granola, paste your Personal API key, and click **Connect**. Granola is a personal connection, so each teammate connects their own account. # Linear > Sync issues and projects for context-aware answers. Connect Linear so Falconer can reason about the work your team is shipping, right alongside your code and docs. ## What's synced Issues, projects, and milestones. ## What you can do - Search tasks alongside code and documentation. - Generate changelogs from completed work. - [Create Linear issues from Slack.](/docs/use-cases/automate-workflows/create-linear-issues-from-falconer) ## Connect Linear 1. Navigate to **Integrations** from the bottom-left menu. 2. Click **Connect** next to Linear. 3. Authorize Falconer to access your Linear workspace. Falconer begins syncing immediately. If your token expires or permissions change, use **Reconnect** to re-authorize. Connecting Linear requires owner permission to your Falconer organization. # Notion > Import pages and databases from your workspace. Connect your Notion workspace so Falconer can search and reason over the pages and databases your team has already written. ## What's synced Pages and databases from the workspace you connect. You choose which pages to sync or import. ## What you can do - Search every connected page and database. - Ask Falcon questions about your Notion content. - Keep Notion knowledge in sync with the rest of your documentation. ## Connect Notion 1. Navigate to **Integrations** from the bottom-left menu. 2. Click **Connect** next to Notion. 3. Authorize Falconer and select at least one page to share. If your token expires or permissions change, use **Reconnect** to re-authorize. You must select at least one page when connecting. If no pages are selected, Falconer has nothing to sync and will prompt you to reconnect. # Slack > Ask questions and manage docs directly from Slack. Bring Falconer into the place your team already talks. With Slack connected, anyone can ask Falcon questions, capture decisions, and turn conversations into living documentation without leaving the workspace. ## What's synced Slack has no active syncing, and Falconer does not index your message history. Falcon searches up to the 15 most recent top-level messages on demand only in a named public channel it has joined. It can load replies from one matching thread, but it does not search older messages, private channels, DMs, or group DMs. Your team can still trigger actions from Slack. ## What you can do - Ask Falcon questions directly in any channel or DM. - Create docs from a conversation or thread. - [Generate Linear issues from a thread.](/docs/use-cases/automate-workflows/create-linear-issues-from-falconer) - Receive Falconer notifications where your team already works. Learn more in [Ask questions in Slack](/docs/ask/ask-questions-in-slack) and [Write a doc from Slack](/docs/write/write-a-doc-from-slack). ## Connect Slack 1. Navigate to **Integrations** from the bottom-left menu. 2. Click **Install** next to Slack. 3. Authorize Falconer in your Slack workspace. Installing Slack requires Slack workspace admin permission and owner permission to your Falconer organization. # Zendesk > Import help center and support articles. Connect Zendesk so your support knowledge is searchable alongside your internal documentation. ## What's synced Help center articles and support content. ## What you can do - Search tickets and help center articles instantly. - Ask Falcon about past tickets and resolutions. - Surface trends across support conversations. Connected articles are searchable alongside the rest of your documentation. ## Connect Zendesk 1. Navigate to **Integrations** from the bottom-left menu. 2. Click **Connect** next to Zendesk. 3. Enter your Zendesk subdomain and authorize Falconer. Zendesk is available on Custom plans. Contact [support@falconer.com](mailto:support@falconer.com) to learn more. # Falconer CLI > Install the Falconer CLI for shell scripts and direct document operations. Use the Falconer CLI when you want direct command-line access to Falconer documents. It is published on npm as [`@falconer/cli`](https://www.npmjs.com/package/@falconer/cli). For AI clients, MCP is the primary setup path. Use the CLI for shell scripts, terminal workflows, and direct document operations. ## Install and sign in Install the CLI: ```bash npm install -g @falconer/cli ``` Sign in with OAuth: ```bash falconer oauth login ``` This opens your browser for Falconer authentication. Your local credentials are stored at `~/.config/falconer/config.json`. Verify your signed-in account and active organization: ```text % falconer oauth status Logged in as xll@falconer.com (org: Lilu's Organization) ``` ## Useful commands Use the help command to list available commands and options: ```bash falconer help falconer --help ``` Manage your session and organization: ```bash falconer oauth status falconer oauth org list falconer oauth org set ``` Search and read docs: ```bash falconer search "runbooks" falconer read ``` Search results include document metadata and a preview. Use the returned `id` or a Falconer URL with `falconer read`. ```text % falconer search "runbooks" --- title: Write runbooks id: dg84gsb9oryxx2mwp5dp4f8e visibility: shared updated: 77d ago --- # Write runbooks Turn your codebase, Slack threads, and notes into step-by-step runbooks ready for the next incident or deployment. Falconer drafts the runbook from your actual systems so it reflects how things really work, not how someone remembered them. ## Prerequisites ... ``` Create or update docs: ```bash falconer create -f runbook.md falconer content replace --old "staging-v1" --new "staging-v2" ``` # Connect MCP > Connect Falconer MCP to Claude.ai, Claude Code, Codex CLI, or Cursor. import { LinkButton } from '@astrojs/starlight/components'; Connect Falconer MCP to your AI client so it can search, read, create, and update Falconer documents. Falconer's MCP endpoint is: ```text https://falconer.com/api/mcp ``` When your client connects, it opens Falconer OAuth in your browser. Sign in with your Falconer account and approve the connection. ## Claude Falconer supports both Claude.ai and Claude Code: add Falconer to Claude.ai as a custom connector, or configure Falconer in Claude Code from the command line. **Claude.ai** Add to Claude.ai This opens Claude with the Falconer connector name and MCP URL prefilled. Connect the connector, then sign in to Falconer when Claude asks for authorization. Manual setup: 1. Open [Claude connectors](https://claude.ai/customize/connectors). 2. Click **Add custom connector**. 3. Set **Name** to `Falconer`. 4. Set the MCP server URL to `https://falconer.com/api/mcp`. 5. Leave **OAuth Client ID** and **OAuth Client Secret** empty. 6. Click **Add**, connect the Falconer connector, and sign in to Falconer when Claude asks for authorization.  **Claude Code** Run this command in a terminal: ```bash claude mcp add --transport http --scope user --client-id falconer-claude-code --callback-port 49152 "falconer" "https://falconer.com/api/mcp" ``` Then open Claude Code and run: ```text /mcp ``` Follow the browser sign-in flow. If port `49152` is unavailable, change it to another local callback port and rerun the command.  ## Cursor Falconer supports both Cursor surfaces: add Falconer to the Cursor app for editor workflows, or configure Cursor Agent for agent sessions. **Cursor app** Add to Cursor app This opens Cursor with Falconer's MCP configuration. Connect the Falconer server, then sign in to Falconer when Cursor asks for authorization. For manual setup, create or update `.cursor/mcp.json` in your project: ```json { "mcpServers": { "Falconer": { "type": "http", "url": "https://falconer.com/api/mcp" } } } ``` Open Cursor MCP settings and complete the Falconer OAuth flow if prompted. **Cursor Agent** Open Cursor Agent 1. Add a new MCP server named `Falconer`. 2. Use `https://falconer.com/api/mcp` as the MCP server URL. 3. Click **Login** to start the OAuth flow for Falconer. ## Codex CLI Falconer supports Codex CLI through an OAuth-backed MCP connection configured from the terminal. Run this command in a terminal: ```bash codex mcp add falconer --url "https://falconer.com/api/mcp" --oauth-client-id falconer-codex-cli --oauth-resource "https://falconer.com/api/mcp" ``` Verify the server is listed: ```bash codex mcp list ```  ## Disconnect MCP Disconnect Falconer in two places if you want to fully remove access. First, revoke Falconer-side authorization. Open [Personal settings > Connected accounts](https://falconer.com/settings/personal#connected-accounts), then disconnect the relevant MCP client. This revokes that client's Falconer OAuth tokens, so it can no longer access Falconer using your account. Then remove Falconer from your MCP client. For Claude Code: ```bash claude mcp remove falconer ``` For Codex CLI: ```bash codex mcp remove falconer ``` For Cursor app, remove the `Falconer` entry from your Cursor MCP config or remove Falconer from Cursor MCP settings. For Cursor Agent, remove Falconer from Cursor Agent MCP settings. For Claude.ai, remove or disconnect the Falconer custom connector from Claude.ai connector settings. For other clients, remove Falconer using that client's MCP documentation. ## Troubleshooting | Issue | What to do | | --- | --- | | Falconer tools do not appear after connecting | Fully restart your MCP client and start a new session. Reconnecting from `/mcp` does not always pick up the tools of a newly added or updated MCP server. | | The client says authentication is required | Reconnect Falconer and complete the browser OAuth flow. | | The client cannot choose an organization | Ask it to call `list_organizations`, then use the returned `organizationId`. | | The token expired or was revoked | Reconnect Falconer from your MCP client. | | Your client does not support Falconer MCP | Use Claude.ai, Claude Code, Codex CLI, Cursor, or another client that supports HTTP MCP. You can also use the Falconer CLI for direct command-line access. | # Use organization bots with MCP > Set up an organization-level Falconer bot for local agents, sandboxes, and MCP clients. Use an organization bot to let autonomous agents read Falconer context without using a person's OAuth session. Organization bots work with the native local MCP server, [`@falconer/mcp`](https://www.npmjs.com/package/@falconer/mcp). Use them for agent harnesses, sandboxes, CI checks, validation loops, and other read-only automation. Use OAuth instead when a human is operating the MCP client. ## Create the organization bot Only organization owners can create organization bots. 1. Open Falconer. 2. Go to **Settings → Organization**. 3. Find **Bot API tokens**. 4. Click **Create bot token**. 5. Enter a clear bot name, such as `Local agent bot` or `CI validation bot`. 6. Copy the token when Falconer shows it. You will not be able to see it again.  If a bot is no longer needed, delete it from **Bot API tokens** to revoke its access. ## Configure the bot ### Credentials file The native `@falconer/mcp` server reads Falconer credentials from: ```text ~/.config/falconer/config.json ``` Create that file with the organization bot token: ```bash mkdir -p ~/.config/falconer chmod 700 ~/.config/falconer cat > ~/.config/falconer/config.json <<'JSON' { "apiKey": "sk_falconer_REPLACE_WITH_YOUR_BOT_TOKEN" } JSON chmod 600 ~/.config/falconer/config.json ``` For local development or another Falconer deployment, add `baseUrl`. It should include `/api`, not `/api/v1`. ```json { "apiKey": "sk_falconer_REPLACE_WITH_YOUR_BOT_TOKEN", "baseUrl": "http://localhost:3000/api" } ``` Restart the MCP client after changing this file. **CLI alternative:** Editing `~/.config/falconer/config.json` is the clearest setup for organization bots. If you prefer to let the Falconer CLI write the same file, use API-key login instead of OAuth: ```bash npx @falconer/cli@latest login ``` The CLI may show a deprecation warning because OAuth is preferred for human users. Paste the organization bot token when prompted, then configure your MCP client to run `@falconer/mcp` as shown above. ### MCP client Add the local Falconer MCP server to your MCP client config. For project-scoped clients such as Claude Code, place this in `.mcp.json` at the project root: ```json { "mcpServers": { "falconer": { "type": "stdio", "command": "npx", "args": ["-y", "@falconer/mcp@latest"] } } } ``` For Cursor, place the same server entry in `.cursor/mcp.json`: ```json { "mcpServers": { "falconer": { "type": "stdio", "command": "npx", "args": ["-y", "@falconer/mcp@latest"] } } } ``` If you install the package globally, you can use the binary directly: ```json { "mcpServers": { "falconer": { "type": "stdio", "command": "falconer-mcp", "args": [] } } } ``` ## Verify access Ask your MCP client to search Falconer: ```text Search Falconer for our deployment runbook. ``` Then read a specific document: ```text Read this Falconer doc: ``` If the bot has access, the client should return matching company-visible docs. If the bot tries to write, Falconer returns a read-only error. ## Access and permissions An organization bot can search and read company-visible docs in its organization, including docs that inherit organization-wide view access. It does not inherit any person's private workspace. Organization bots are read-only. Falconer rejects writes such as creating, updating, moving, or deleting docs; uploading media; changing permissions; or creating, editing, or resolving comments. Create separate bots for separate environments or agent roles. ## Rotate or revoke a bot To rotate a bot credential: 1. Create a new bot token. 2. Replace the `apiKey` value in `~/.config/falconer/config.json`. 3. Restart the MCP client. 4. Delete the old token from **Bot API tokens**. Deleting a bot token revokes it immediately. # Quickstart with MCP > Connect Falconer MCP to your AI client, sign in with OAuth, and verify that your client can reach your Falconer documents. import { LinkButton } from '@astrojs/starlight/components'; Use this quickstart to prove that Falconer MCP is connected and working from your AI client. Falconer MCP gives Claude, Codex, Cursor, and other compatible clients access to Falconer through an HTTP endpoint. ## Claude Falconer supports both Claude.ai and Claude Code: add Falconer to Claude.ai as a custom connector, or configure Falconer in Claude Code from the command line. **Claude.ai** Add to Claude.ai This opens Claude with the Falconer connector name and MCP URL prefilled. Connect the connector, then sign in to Falconer when Claude asks for authorization. **Claude Code** Run this command in a terminal: ```bash claude mcp add --transport http --scope user --client-id falconer-claude-code --callback-port 49152 "falconer" "https://falconer.com/api/mcp" ``` Then run `/mcp` in Claude Code and complete the browser sign-in flow. ## Cursor Falconer supports both Cursor surfaces: add Falconer to the Cursor app for editor workflows, or configure Cursor Agent for agent sessions. **Cursor app** Add to Cursor app This opens Cursor with Falconer's MCP configuration. Connect the Falconer server, then sign in to Falconer when Cursor asks for authorization. For manual setup, create or update `.cursor/mcp.json` in your project: ```json { "mcpServers": { "Falconer": { "type": "http", "url": "https://falconer.com/api/mcp" } } } ``` Open Cursor MCP settings and complete the Falconer OAuth flow if prompted. **Cursor Agent** Open Cursor Agent Add a new MCP server named `Falconer`, use `https://falconer.com/api/mcp` as the server URL, then click **Login** to start the Falconer OAuth flow. ## Codex CLI Falconer supports Codex CLI through an OAuth-backed MCP connection configured from the terminal. Run this command in a terminal: ```bash codex mcp add falconer --url "https://falconer.com/api/mcp" --oauth-client-id falconer-codex-cli --oauth-resource "https://falconer.com/api/mcp" ``` ## Verify the connection Ask your client to make a simple Falconer MCP call: ```text List my Falconer organizations. ``` Then try a search: ```text Search Falconer for our deployment runbook. ``` Or read a specific Falconer document: ```text Read this Falconer doc: ```  ## Multiple organizations If your account has access to one Falconer organization, your client can usually omit `organizationId`. If your account has access to multiple organizations, first ask the client to list organizations. Then include the selected `organizationId` in future Falconer requests. # MCP tools reference > Review the Falconer MCP tools for documents, comments, navigation, permissions, and media. Falconer MCP exposes tools your AI client can use to find, read, create, update, organize, and manage Falconer documents.  ## Organization discovery | Tool | What it does | | --- | --- | | `list_organizations` | Lists Falconer organizations available to the MCP connection. | If only one organization is available, your client can usually omit `organizationId`. If multiple organizations are available, pass the selected `organizationId` on future Falconer tool calls. ## Find and read documents | Tool | What it does | | --- | --- | | `search` | Searches Falconer documents by keyword query, semantic query, or both. | | `read` | Reads a Falconer document by document ID, title, or Falconer URL. | Use `search` when you do not know the exact document. Use `read` before editing so the agent can copy exact Markdown text from the current document. ## Create and update documents | Tool | What it does | | --- | --- | | `create` | Creates a Falconer document from Markdown. | | `replace_document_content` | Replaces exact Markdown text in a document. | | `insert_document_content` | Inserts Markdown before or after exact anchor text, or at the start or end of a document. | | `delete_document_content` | Deletes exact Markdown text from a document. | | `edit` | Legacy exact replacement tool. Prefer the targeted content tools above. | | `overwrite` | Replaces the full Markdown body of a document. | | `delete` | Archives a Falconer document by ID. | Prefer `replace_document_content`, `insert_document_content`, and `delete_document_content` for targeted updates. Use `overwrite` only when the whole document needs to be rewritten. ## Comments | Tool | What it does | | --- | --- | | `list_document_comments` | Lists comment threads on a Falconer document. | | `reply_to_comment` | Replies to an existing document comment. | | `edit_comment` | Edits one of your existing comments. | | `delete_comment` | Deletes one of your existing comments. | | `resolve_comment` | Resolves a document comment thread. | | `unresolve_comment` | Reopens a resolved document comment thread. | ## Navigation and folders | Tool | What it does | | --- | --- | | `list_nav_children` | Lists visible child folders and documents for a navigation location. | | `get_nav_tree` | Gets a visible Falconer navigation tree. | | `get_folder` | Gets folder metadata and visible one-level children. | | `create_folder` | Creates a Falconer folder. | | `update_folder` | Updates a folder title or description. | | `reorder_folder_children` | Sets the full direct-child order for a folder. | | `reorder_nav_children` | Sets the full direct-child order for a folder or document nav item. | | `move_nav_item` | Moves a folder or document navigation item. | | `move_document` | Moves a document navigation placement by document ID. | | `publish_document` | Publishes a private document into company navigation. | | `delete_folder` | Archives a folder and its documents. | Inspect navigation placement before moving documents or folders. If a document move or publish reports ambiguous placement, retry with the returned `sourceNavItemId`. ## Permissions and media | Tool | What it does | | --- | --- | | `update_document_permissions` | Updates document ACL mode, organization-wide access, public access, user access, or group access. Direct permission changes on inherited documents switch them to explicit mode automatically. | | `upload_media` | Uploads an image or video and returns a snippet that can be inserted into document content. | ## Permissions The MCP connection uses the permissions of the authenticated Falconer user or organization bot. Your client can only access documents, folders, comments, and permissions that identity can access in Falconer. # Organize docs > Falconer Organize analyzes your Company documents and proposes a reorganized structure with new folders, categories, and architecture. Falconer Organize analyzes your Company documents and proposes a reorganized structure with new folders, categories, and architecture. ## Prerequisites Falconer Organize is a Pro feature. ## 1. Open Organize Right click on **Company documents** in the left nav to access Organize.  Falconer scans your Company documents and generates a proposed information architecture with folder structure, document groupings, and naming. ## 2. Talk to the agent Organize immediately offers its initial analysis on your information architecture. You can tell the agent to adjust the proposal before applying anything. **Example prompts:** ``` Group all the onboarding docs under a single folder ``` ``` Rename the Engineering section to Product & Engineering ``` ``` Which docs haven't been updated in over 6 months? Put them in a 'Needs review' folder ``` ``` Are there any duplicate pages? ``` The agent responds and updates the proposed structure in real time. > **Note:** You can ask Falconer to focus on a specific folder to organize. ## 3. Review the proposal The right pane shows a before and after of your document hierarchy. ## 4. Apply changes When the proposal looks right, click **Apply**. Your left sidebar updates immediately to reflect the new structure. # Allowlist a domain > Use the domain allowlist to allow teammates in your organization to log in with SSO. Use the domain allowlist to allow teammates in your organization to log in with SSO. When you add a domain, anyone who signs in with a matching company email address is instantly added to your Falconer organization. ## Set up your allowlist Only owners can manage the domain allowlist. 1. Go to **Organization Settings**. 2. Go to the **Domain allowlist** section. 3. Enter your company domain (for example, `yourcompany.com`) and click **Add domain**. You can add multiple domains and remove them at any time. Once a domain is allowlisted, any user who signs in with a matching email is automatically added to your organization as a member. Members can create and edit documents and access all published company content. You can update their role to owner at any time from Organization Settings. ## Confirm a domain from a sign-in prompt If a teammate signs in with a company email that isn't yet on your allowlist, Falconer may prompt you to confirm their domain. Confirming it adds the domain to your allowlist so all future sign-ins from that domain are approved automatically. ## What's not allowed - **Free or public email domains** (like `gmail.com`, `yahoo.com`) - **Invalid formats** (like incomplete domains) ## Allowlist vs manual invites The allowlist and manual invites work together: | Method | Best for | | --- | --- | | Domain allowlist | Automatically onboarding your whole team by email domain | | Manual invite | Adding specific individuals, contractors, or users from other domains | Manual invite links are valid for 7 days. If a link expires, an owner can resend it from Organization Settings. # Connect sources > Connect your tools to Falconer to enable code-aware search, AI-powered documentation. Connect your tools to Falconer to enable code-aware search, AI-powered documentation. Connecting a source takes a few clicks. Connect GitHub and start asking questions and writing docs about your codebase in minutes. ### Prerequisites - Admin permission to the source you're connecting (for example, GitHub organization admin or Slack workspace admin) - Owner permission to your Falconer organization  ### Steps 1. Navigate to *Integrations* from the bottom-left menu. 2. Click **Connect** next to the source you want to add. 3. Authorize Falconer to access your account on the third-party provider's page. 4. Select the specific resources you want to sync (for example, individual GitHub repositories or Confluence spaces). 5. Falconer begins syncing immediately. Initial indexing typically completes within minutes. ## Supported sources Each source has its own setup page with what's synced, what you can do, and how to connect. Browse them all in [Integrations](/docs/integrations). See which integrations are available for your plan on the [pricing page](https://falconer.com/pricing). ## Connection states Each source card on the *Integrations* page shows a button that reflects its current state. A green dot on a source card means it's actively connected and syncing. Sources also display a "Last synced" timestamp so you can confirm data is up to date. | Button | Meaning | | --- | --- | | Connect / Install | The source isn't connected yet. Click to start the authorization flow. Slack shows "Install" instead of "Connect." | | Configure | The source is connected and has additional settings. Click to manage which repositories, spaces, or other resources are synced (used by GitHub, Confluence, and Zendesk). | | Reconnect | The source is connected but uses the default action. Click to re-authorize if your token expired or permissions changed (used by Linear and Notion). | | Disconnect | The source is connected and can be removed. Click to revoke access and uninstall (used by Slack). | | Instructions | The source requires manual setup outside Falconer. Click to view step-by-step configuration instructions (used by Google Drive's targeted connection). | # Invite teammates and manage permissions > Get your team into Falconer and control what they can see and edit. Get your team into Falconer and control what they can see and edit. ## Organization roles Falconer has two roles at the organization level: | Role | What they can do | | --- | --- | | **Owner** | Invite and remove members; manage org settings; manage doc permissions | | **Member** | Create and edit documents; access published company content | ## Invite teammates Only owners can invite new members. If you don't see the option to invite a teammate, ask your org owner to send the invite. 1. In the bottom left, go to **Your org name -> Invite user.**  2. Enter your teammate's email address and select a role. 3. Click **Invite**. Falconer sends the teammate an invite link valid for 7 days. Once they accept, they're added as a member of your organization and can access all published company documents. ## Manage permissions Use permissions to control who can view, comment on, edit, and share docs and folders. Start with [**Plan doc access**](/docs/use-cases/manage-permissions/plan-doc-access) to understand permission levels, inherited permissions, and custom permissions. Then use: - [**Share a doc**](/docs/use-cases/manage-permissions/share-a-doc) -- Manage access, authors, organization access, and link access for one doc. - [**Manage folder access**](/docs/use-cases/manage-permissions/manage-folder-access) -- Manage access for a folder and the docs that inherit from it. - [**Choose inherited or custom permissions**](/docs/use-cases/manage-permissions/choose-inherited-custom-permissions) -- Decide when a doc or folder should follow its parent permissions. ## Publish to the company collection Documents start in your Private collection, visible only to you. To make a document searchable and visible across your organization: 1. Click **Publish** at the top of the document.  2. Choose a location in the company collection. Falconer suggests one based on the content. Published documents are accessible to all org members and surfaced by Falconer in search and Q&A. ## Access requests If a teammate tries to open a document they don't have access to, they'll see a **Request Access** button. This sends a Slack notification to the document owner, who can grant access directly from Slack -- either for that individual or for the whole org. ## Permissions and the Falcon agent The Falcon agent only surfaces documents the requesting user has permission to see. Docs with restricted access won't appear in search results or agent answers for users who don't have access. # Automatically update documents > Turn on auto-update for any document and Falconer will keep it current, automatically. When a pull request merges, Falconer reads the diff, finds which docs are affected, and proposes changes for your review. Turn on auto-update for any document and Falconer will keep it current, automatically. When a pull request merges, Falconer reads the PR, finds which docs are affected, and proposes changes for your review. ## Prerequisites - **Pro subscription** - Sign up for a free trial at https://falconer.com/pricing - **GitHub integration** — GitHub App installed with repositories connected to Falconer so Falconer can detect updates - **Slack integration** — Falconer agent connected with DM permissions enabled to receive notifications - **Document ownership** — you must be the document owner to receive notifications (document creators are owners by default) - **Document visibility** — auto-update only works on documents with org-wide or public visibility; private documents are excluded ## Enable auto-update Auto-update is off by default. When you publish a doc, a banner appears at the top of the editor to toggle it on.  To turn it on or off for a document if you have dismissed the banner: 1. Open the document in the editor 2. Click the more button on top right corner, and select **Details** in the right sidebar 3. Toggle **Auto-update** on ## How it works When you first toggle on auto-update, we will run an initial workflow to update your doc immediately. When a pull request merges in a connected repository: 1. Falconer search identifies impacted documents 2. Falconer proposes edits for the impacted document 3. Document owners are notified by Slack DM with a summary and action buttons  ```mermaid flowchart TD A[Pull request merges] --> B[Falconer finds impacted docs] B --> C[Falconer drafts edits] C --> D{"Update
mode"} D -->|Full self-driving| E[Changes applied to published doc] D -->|Review| F[Draft held for owner review] E --> G{"Notification
cadence"} F --> H{"Notification
cadence"} G -->|Immediate| G1[Slack DM sent right away] G -->|Digest| G2[Bundled into a digest] H -->|Immediate| H1[Slack DM sent right away] H -->|Digest| H2[Bundled into a digest] H1 --> J{"Doc owner
action"} H2 --> J J -->|Accept| K[Draft applied to published doc.
Slack confirms with link.] J -->|Review| L[Open in Falconer editor with inline diff.
Accept or reject all or selected changes.] J -->|Reject| M[Draft discarded.
No changes made.] ``` ## Update mode When you enable auto-update, the default mode is **Full self-driving mode** — Falconer applies changes to the document immediately without a review step. You can switch to **Review mode** in the Details panel. In this mode, Falconer holds proposed changes for your review and notifies you in Slack. ## Multiple PRs, one document When multiple pull requests affect the same document before you’ve reviewed pending changes, Falconer reconciles them into a single consolidated draft. You review one set of changes instead of one per PR. ## Troubleshooting **Not receiving notifications** - Confirm you are listed as the document owner - Check that Slack DM permissions are enabled for the Falconer bot - Verify the GitHub integration is active and the repository is connected **Document not picked up by auto-update** - Confirm auto-update is toggled on in the Details panel - Check that the document is not set to private visibility # Edit a doc with inline AI > Use inline AI to make targeted edits to specific sections instead of regenerating an entire page. Use inline AI to make targeted edits to specific sections instead of regenerating an entire page. Highlight any text in the Falconer editor and use AI to transform it. ## Make targeted edits To use inline AI: 1. Open any document in the Falconer editor. 2. Highlight the text you want to change. 3. Type what you want in the inline prompt bar. 4. Review the result and **Accept** or **Discard.** > **Note:** Not sure what you want to change yet? Chat with Falcon to explore changes before committing. ## Example prompts Here are some examples for how you might edit part of your doc with inline AI. ### Convert format Transform content between different structures: ``` Turn this list into a table ``` ### Improve writing Clean up and strengthen existing content: ``` Edit this for clarity ``` ### Expand or condense Add depth or trim down a section: ``` Add an example ``` ``` Make this more concise ``` ### Translate Convert content between languages: ``` Translate this to Spanish ``` # Find and fix outdated docs > Ask Falcon to audit your documentation for staleness -- from inside a doc or from the homepage -- and get a prioritized list of what needs updating. Ask Falcon to audit your documentation for staleness -- from inside a doc or from the homepage -- and get a prioritized list of what needs updating. ## From inside a doc When you're working in a document and want to know if it's still accurate, ask the agent directly in the editor: ``` What's out of date in this doc compared to the codebase? ``` Falcon cross-references the document against your connected sources -- GitHub, Linear, other docs -- and shows you sections that may need updating, with citations to what changed. From there, you can ask Falcon to draft the fix inline: ``` Update the authentication section to reflect the new token refresh logic ``` ## From the homepage To audit your entire knowledge base at once, ask on the Falconer homepage: ``` Find the docs that are outdated ``` Falcon returns a list of documents ranked by likely staleness, with a brief explanation of why each one may need attention -- for example, referencing a file that changed recently, or conflicting with another document.  Continue the conversation with the agent to make any updates. To get a more focused answer, ask about specific sections: ``` What's outdated in the API reference? ``` ## Automate finding and fixing - [**Automatic updates from PRs**](/docs/update/keep-docs-in-sync-with-prs) -- Falcon can also notify you when a merged pull request affects your docs. - [**Capture new decisions**](/docs/ask/capture-decisions-in-slack) -- Use `@Falcon remember` in Slack to save decisions before they get lost. # Keep docs in sync with PRs > Get notified when pull requests impact your docs. Falconer automatically detects when a merged pull request impacts your existing documentation and proposes targeted updates. Get notified when pull requests impact your docs. Falconer automatically detects when a merged pull request impacts your existing documentation and proposes targeted updates -- delivered straight to document owners through Slack. > **Note:** Automatic doc updates is a new feature. Contact us at support@falconer.com for a demo. ## Prerequisites Before enabling automated documentation updates, make sure you have: - [Connected your GitHub App and Slack workspace](/docs/set-up/connect-sources) to Falconer - Been assigned as an owner of the documents you want to receive updates for ## How it works When a PR merges, Falconer analyzes the code changes, identifies which documents are affected, drafts proposed updates, and notifies the right people. Owners can accept, review, or reject changes without leaving Slack. ```mermaid flowchart LR PR([PR merges]) --> Notify[You get a Slack notification] Notify --> Accept[Accept] Notify --> Review[Review & edit] Notify --> Reject[Reject] Accept --> Done([Doc updated]) Review --> Done Reject --> Skip([No changes]) ``` ## Update notifications If a PR impacts a doc you own, you'll receive a notification in Slack.  **Accept** -- Changes apply immediately to the document. **Review** -- Opens the document in the Falconer editor with a **side-by-side diff** of the proposed changes. You can make manual edits before accepting or rejecting. **Reject** -- Discards the proposed changes entirely. # Update docs from Slack > Update your Falconer docs directly from Slack conversations. Update your Falconer docs directly from Slack conversations. ## Prerequisite Ensure [Slack is connected](/docs/set-up/connect-sources) to your Falconer org. ## Update a doc Mention `@falcon` and it will search your organization's documentation, identify the right document, and apply targeted edits based on the conversation context.  To update a doc: 1. Mention Falcon with your update request. For example: ``` @Falcon update the runbook with the new staging deploy steps ``` 2. Falcon analyzes the conversation and searches for matching docs 3. Falcon identifies the correct document(s) 4. Confirm docs you want to update ## Tips for better updates - **Be specific in your request.** Tell Falcon which doc to update and what information to add. The more context you provide, the more accurate the update. - **Reference the doc by name.** If you know the document title, include it in your message to skip the selection step. - **Use threads.** Falcon reads the full thread context, so reply in a thread where the relevant discussion happened. - **Update tables from Slack.** Falcon handles structured content like tables -- mention the specific rows or columns to change. # Create Linear issues from Falconer > Create Linear issues from Slack conversation or Falconer docs. Create Linear issues from Slack conversation or Falconer docs. ## Prerequisites Before creating Linear issues from Slack, make sure: - **Slack is connected** -- An admin has installed the Falconer Slack app in your workspace - **Linear is connected** -- An admin has connected your Linear organization in Falconer settings - **Pro plan** -- Creating Linear issues from Slack requires a Pro subscription ## Create a Linear issue from Slack Ask `@falcon` within Slack to create issues from Slack conversations. Falconer reads the full thread context and generates a title and description for you. **Example prompts:** ```markdown @falcon create a ticket for this bug ``` ```markdown @falcon file a task for me to follow up on this ``` ```markdown @falcon turn this thread into a Linear issue ``` Falconer generates a preview message in the thread to confirm project and assignee:  ## Create issues from a doc You can ask Falconer to create multiple issues from a single message. Falconer analyzes the document and generates individual issues for relevant items:  # Sync Granola meeting notes > Connecting Granola syncs your meeting notes into Falconer, making them searchable alongside your docs, code, and conversations. Connecting Granola syncs your meeting notes into Falconer, making them searchable alongside your docs, code, and conversations. Falcon can reference meeting context when answering questions, writing docs, or surfacing decisions. ## Prerequisites - A [Granola](https://granola.so/) account with existing meeting notes - Owner or admin access to your Falconer organization ## Generate a Granola API key 1. Open the [Granola](https://granola.so/) app. 2. Click **Settings** (top right). 3. Go to **Connectors → API keys**. 4. Click **Create new key**. 5. Select the **Personal** scope (add **Public** if you want team-shared notes). 6. Click **Generate API key** and copy it. ## Connect Granola to Falconer  1. Navigate to **Integrations** from the bottom-left menu in Falconer. 2. Find **Granola** and click **Connect**. 3. Paste your Granola API key and click **Connect**. 4. Falconer begins syncing your meetings immediately.  > **Note:** Falconer connects one Granola account per user in your organization. It gets access to all meetings belonging to the authenticated user. ## What gets synced Each meeting is ingested as a structured document containing: - Meeting title and date - Attendee names and email addresses - Meeting summary and notes Meetings are organized into date-based folders under a **Meeting notes** section in your personal navigation. ## After connecting Once synced, your Granola meeting notes are indexed alongside your other sources. From there you can: - **Ask questions** -- Falcon answers questions using your meeting content, with citations back to the source note - **Write docs** -- reference meeting context when prompting Falcon to write or update documentation - **Surface decisions** -- ask Falcon what was decided in a meeting, who owns an action item, or what was discussed on a given topic # Talk to the Falconer agent like a teammate > Get answers and capture your knowledge in plain conversation -- no prompts required. Get answers and capture your knowledge in plain conversation -- no prompts required. Falcon is the AI agent built into Falconer. You don't need to learn special commands or write in a particular way. Just ask what you'd ask a knowledgeable teammate, and Falcon finds the answer, writes the doc, or helps you get information out of your head. ## Prerequisites To get the most out of Falconer: - [Connect Slack](/docs/set-up/connect-sources) so you can talk to Falcon where you already work, without switching tools - Add key documents to Falconer -- the more context Falcon has, the better its answers and drafts ## Get instant answers From the Falconer homepage, or by mentioning `@Falcon` in any Slack channel, just ask.  Here are some example questions: ``` How does our refund process work? ``` ``` Who owns the billing service? ``` ``` What did we decide about the new onboarding flow? ``` Falcon searches across your connected docs, conversations, and other sources, then gives you a cited answer so you can see exactly where the information came from. ## Get knowledge out of your head Falcon can help you turn what you know into a doc without spending hours writing it. Start a conversation: ``` I want to document how we handle customer escalations. Ask me questions and I'll answer them. ``` ``` Help me write down how the deployment process works. I'll describe it and you turn it into a doc. ``` Falcon asks you questions, fills in what it already knows from your connected sources, and drafts the doc for you to review. ## Capture knowledge from a conversation If a Slack thread already contains the answer, you don't need to rewrite it. [Write a doc from a thread.](/docs/write/write-a-doc-from-slack) For smaller facts and decisions that don't need a full doc, [use @Falcon remember in Slack](/docs/ask/capture-decisions-in-slack) to save them instantly. ## Refine the draft Once Falcon produces a draft, keep the conversation going to shape it. Fill in the gaps: ``` What's missing from this doc? ``` Simplify: ``` Make this easier to follow for someone new. ``` Add context: ``` Include a section on why we made this decision ``` Adjust length: ``` This is too long -- trim it down ``` Check accuracy: ``` Does this match what's in our other docs? Is this up to date with the codebase? ``` # Update docs when code changes > Automatically keep documentation in sync with your codebase as your team ships. Automatically keep documentation in sync with your codebase as your team ships. Falconer monitors your [connected](/docs/set-up/connect-sources) GitHub repositories and, when a pull request merges, identifies which existing docs are affected and proposes updates. ## Review automated updates When a PR merges in a connected GitHub repository, Falconer automatically detects the affected docs and sends the document owner a Slack notification with **Accept**, **Review**, or **Reject** options. See [Keep docs in sync with PRs](/docs/update/keep-docs-in-sync-with-prs) for a full breakdown of the notification flow. ## Trigger a manual update You can also trigger an update manually -- before a PR merges, or when you want more control over the scope of the update. ### Trigger an update within a doc Use a prompt like this from any doc: ``` Our auth flow will change in this PR: [link]. Update the authentication docs to reflect the new token refresh logic and remove any references to the old session handling approach. ``` ### Find stale information across docs Alternatively, ask Falcon to do a broader check before a release across your docs. In the prompt box on the home page, try: ``` Do a full review of the rate limiting API docs and update anything that's out of date -- I want to make sure everything is in sync before we publish. ``` ## Iterate on the update Once Falcon drafts the update, open the document and type **/** to open Falcon in the editor to refine it. You can ask the agent to: - **Confirm the scope** -- learn which sections need updating and which should stay unchanged - **Ensure accuracy** -- cross-reference the PR diff against the existing doc - **Refresh code samples** -- update snippets that reflect the new implementation - **Update diagrams** -- regenerate architecture or flow diagrams to match the new behavior - **Tailor the tone** -- adjust the depth and language for the right reader (like internal engineers vs. external API consumers) - **Find related docs** -- surface other docs that may also be affected by the same change Once you're satisfied, accept the changes and they'll be saved directly to the published doc. # Create an onboarding guide > Create role-specific onboarding guides for new hires using existing context. Create role-specific onboarding guides for new hires using existing context. Falconer generates personalized onboarding guides pulling context from your actual codebase, tasks, and internal docs. ## Prerequisites Connect your sources for the best results: - [Connect GitHub](/docs/set-up/connect-sources) to pull context directly from your codebase - [Connect Linear](/docs/set-up/connect-sources) to include real tasks in the onboarding guide - Upload or reference key documents (job description, plan, job ladder) as additional context ## Draft the guide Here's a starter prompt to create a guide specific to your new hire: ```markdown Create an onboarding guide for our new fullstack engineer. Reference the job description from @[job description in your Falconer org]. Include a day-by-day plan for their first two weeks: - set up their developer environment - development lifecycle and how to deploy to production - link to relevant Linear tasks for their onboarding phase - add diagrams of key services, systems, and flows ``` Alternatively, you can collaborate with Falconer with a more guided approach. Falconer will ask you questions before writing the guide: ```markdown Help me write an onboarding guide for our new engineer. ``` ## Iterate on the guide Because Falconer has access to your connected sources, the onboarding guide includes context specific to your organization. Once the doc is drafted, you can use the agent in the right pane to ensure it has key information for your new hire, such as: - **Architecture diagrams** -- include visual overviews of your codebase - **Code samples** -- ask Falconer to include helpful code snippets or commands for setup or common tasks - **Tasks** -- ask Falconer to include real Linear issues the new hire can pick up during onboarding - **Sequencing** -- ensure the length of the onboarding and order of operations are correct - **Key documents** -- reference relevant internal docs, runbooks, and style guides - **Key context** -- include which Slack channels to join, which repos to clone, and who to talk to # Create architecture overviews > Ask Falconer to explain how any part of your codebase works -- from high-level system architecture down to how a specific feature is implemented. Ask Falconer to explain how any part of your codebase works -- from high-level system architecture down to how a specific feature is implemented. Falconer reads your connected repositories and synthesizes answers with citations to the actual files. ## Prerequisites [Connect GitHub](/docs/set-up/connect-sources) as a source so Falconer can read your codebase. ## Ask about your architecture Use the agent from the homepage or the editor sidebar. Ask in plain language -- no need to know which files are relevant: ``` Give me an overview of how this codebase is structured ``` ``` How does our authentication flow work end-to-end? ``` ``` Explain the relationship between our API gateway and the services behind it ``` Falconer searches across your connected repositories, synthesizes an explanation, and cites the specific files and functions it drew from.  ## Generate diagrams Ask Falconer to produce a visual diagram of any system, service, or data flow: ``` Create an architecture diagram for the notification service ``` Diagrams are rendered inline as interactive Mermaid diagrams. You can ask Falconer to adjust the scope or level of detail. ## Drill into specific implementations Once you have the high-level picture, follow up to go deeper: ``` How is retry logic handled in the webhook service? ``` ``` Walk me through how we handle session expiry ``` Use **@** to focus Falconer on specific files or directories:  ## Turn answers into documents After getting an explanation you want to preserve, ask Falconer to write it up: ``` Write a doc explaining what you just described ``` The draft opens in the editor, where you can refine it and publish it to your company collection. # Generate a weekly team report > Summarize what your team shipped, what's in progress, and what's blocked in minutes. Summarize what your team shipped, what's in progress, and what's blocked in minutes. Falconer reads your connected GitHub and Linear data to compile the week's activity into a structured report ready to share. To add Slack context, name a public channel that Falcon has joined; Falcon can check that channel's recent messages. ## Prerequisites [Connect your tools](/docs/set-up/connect-sources) to Falconer: - GitHub to pull in merged PRs and code changes - Linear to pull in completed and in-progress tasks - Slack for recent context from a named public channel that Falcon has joined ## Generate the report On the Falconer homepage, in the sidebar, or in Slack, ask Falconer to write the draft: ``` Write a weekly engineering report for this week ``` Falconer pulls merged pull requests from GitHub, completed and in-progress tasks from Linear, and synthesizes them into a structured report ready to share. ## Scope to a specific team or project If you have multiple teams or want to focus on a particular area: ``` Write a weekly report for the infrastructure team only ``` ``` Generate a report covering only the billing project this week ``` ## Iterate on the draft Once the draft is open in the editor, use Falcon in the sidebar to refine it. Rewrite highlights for a leadership audience: ``` Rewrite the highlights section for a non-technical audience ``` Check for any PRs or tasks that may have been missed: ``` Check if there are any merged PRs from this week that aren't reflected in the report ``` Add deploy counts, incident counts, or other stats: ``` Add a metrics section with deploy count and any incidents from this week ``` Pull open Linear issues to populate the plan section: ``` Populate next week's plan from open Linear issues assigned to the team ``` ## Share the report Once the report is ready, publish it to your company collection so it's findable by your team and leadership. To generate and share a report without leaving Slack, ask Falcon directly in the channel: ``` @Falcon write a summary of what the engineering team shipped this week and post it here ``` # Generate an API reference from code > Turn your codebase into a structured API reference. Falconer reads your connected repositories and generates documentation for your endpoints, functions, parameters, and return types. Turn your codebase into a structured API reference. Falconer reads your connected repositories and generates documentation for your endpoints, functions, parameters, and return types -- ready to review and publish. ## Prerequisites Connect Falconer to your codebase: 1. [Connect GitHub](/docs/set-up/connect-sources) as a source. 2. From the bottom-left menu in Falconer, go to **Integrations** and click **Configure** next to GitHub. 3. Follow the prompts and select the repository containing your API. Wait for the initial sync to complete before generating documentation. ## Generate the reference Use the prompt box on the [Falconer homepage](https://falconer.com) to kick off the draft, or ask `@falcon` in Slack. Be specific about what you want documented: ``` Write an API reference for our payments service ``` ``` Generate endpoint documentation for the routes in /api/v1 ``` ``` Document the public methods in src/services/auth.ts ``` Falconer reads the relevant files, infers structure from your code, and produces a draft with endpoints, parameters, request/response shapes, and descriptions. ## Reference specific files Use **@** to point Falconer at the exact files or directories you want documented: ``` Write an API reference for @src/routes/payments.ts and @src/routes/webhooks.ts ``` ``` Document the public API surface in @src/server/public-api ``` This is especially useful for large codebases where you want to scope the output to a specific service or module. ## Iterate on the draft Once Falconer generates the draft, use the Falcon agent in the right pane or type **/Falcon** to refine it: 1. Check completeness. Ask Falconer to verify nothing is missing: ``` Check @src/routes/payments.ts and make sure all parameters are documented accurately ``` 2. Add examples. Request examples for each endpoint: ``` Add a request and response example for each endpoint ``` 3. Adjust for your audience. Tell Falconer who will read it: ``` Rewrite this for external developers unfamiliar with our system ``` 4. Publish when ready. Move the doc from your private space to the company collection. ## Keep it up to date Once your API reference is published, Falconer monitors your connected repositories for changes. When a PR merges that affects documented endpoints, Falconer suggests doc updates for your review -- so your reference stays accurate as your API evolves. # Write a changelog > Generate a changelog using context from your connected sources. Generate a changelog using context from your connected sources. ## Prerequisites Recommended [sources](/docs/set-up/connect-sources) for a high-quality changelog: - Connection to GitHub to find recent pull requests - Connection to Linear to find recent tasks ## Draft the changelog Falconer searches your connected Linear issues and pull requests to generate a changelog. **Steps:** 1. Click the **+** icon in the left sidebar to create a new doc. 2. In the agent chat, be specific about the time range, team, or project you want to cover. Example prompts: ```markdown Write a changelog for the last two weeks ``` ```markdown Summarize what the engineering team shipped this sprint ``` ```markdown Create a changelog for the payments project dating back to January 1 ``` ```markdown Write release notes for everything completed last month, grouped by theme ``` ## Collaborate on the changelog Alternatively, you can collaborate with Falconer from the homepage with a more guided approach. Falconer will prompt you with questions before writing the changelog.  # Write a runbook > Turn your codebase, Slack threads, and notes into step-by-step runbooks ready for the next incident or deployment. Turn your codebase, Slack threads, and notes into step-by-step runbooks ready for the next incident or deployment. Falconer drafts the runbook from your actual systems so it reflects how things really work, not how someone remembered them. ## Prerequisites [Connect sources](/docs/set-up/connect-sources) like GitHub and Slack so Falconer can read your codebase and pull in context from past incidents and discussions. ## Draft a runbook Use Falcon to start the draft. Be specific about the service or scenario: ``` Write a runbook for deploying the payments service ``` ``` Create an incident response runbook for database connection failures ``` Falconer reads your connected repositories, finds the relevant code and configuration, and produces a structured runbook with steps, commands, and context. ## Build from a past incident If your team resolved an incident in Slack, ask Falconer to turn that thread into a runbook so the fix is documented for next time.  Falconer reads the thread, extracts the resolution steps, and structures them into a reusable runbook. ## Reference specific files Use **@** to point Falconer at the exact services, scripts, or config files you want the runbook to cover: ``` Write a deployment runbook for @src/services/ingest using @infra/deploy.sh ``` ``` Create a rollback runbook based on @scripts/rollback.sh and @infra/pulumi/instance ``` ## Iterate on the draft Once the draft is open in the editor, use the agent in the right pane to refine it: - **Commands** -- ask Falconer to verify commands against your actual scripts or add missing flags - **Sections** -- add a prerequisites section, an escalation path, or a rollback procedure - **Audience** -- adjust the level of detail for a junior on-call engineer vs. a senior SRE - **Edge cases** -- ask Falconer to identify failure modes or gotchas based on your code ## Keep runbooks up-to-date Once published, Falconer monitors your connected repositories for changes. When a PR merges that affects a service your runbook covers, Falconer flags the runbook and proposes updates -- so your procedures stay accurate as your infrastructure evolves. You can also manually audit your runbooks for staleness at any time. See [Find and fix outdated docs](/docs/update/find-and-fix-outdated-docs). # Choose inherited or custom permissions > Decide whether a doc or folder should follow its parent permissions or keep its own access settings. Each doc and folder can follow its parent permissions or keep its own access settings. ## Use inherited permissions Use inherited permissions when a doc or folder should follow the access settings around it. This works best when: - A whole folder should be available to the same team - New docs should automatically match the folder they are created in - You want to manage access from one parent folder instead of each doc When inherited permissions are on, Falconer shows where the access comes from. ## Use custom permissions Use custom permissions when a doc or folder needs different access than its parent. This works best when: - One doc is more sensitive than the rest of the folder - A subfolder should be editable by a smaller group - A doc needs link access, but the folder around it does not - A doc needs a different author list ## Turn inherited permissions off To switch to custom permissions: 1. Open the doc or folder share dialog. 2. Turn **Inherit permissions** off. 3. Review the copied access settings. 4. Update people, groups, organization access, or link access as needed. Falconer starts with a copy of the current effective permissions, so access does not unexpectedly disappear when you switch. ## Turn inherited permissions on To switch back to inherited permissions: 1. Open the doc or folder share dialog. 2. Turn **Inherit permissions** on. The doc or folder stops using its custom access settings and follows the nearest parent permissions instead. ## Choose the right approach | Situation | Recommended setting | | --- | --- | | Most docs in a folder should have the same access | Inherited permissions | | A single doc needs different access | Custom permissions | | A subfolder should manage its own docs | Custom permissions on the subfolder | | You want future docs to follow a folder automatically | Inherited permissions | If you are unsure, keep inherited permissions on and manage access from the folder. # Manage folder access > Use folder permissions to manage access for groups of related docs. Use folder sharing when a set of related docs should be available to the same people. Folder permissions apply to docs and folders inside the folder when those descendants use inherited permissions. ## Open folder sharing 1. Open the folder. 2. Click **Share** in the folder header. The folder share dialog shows whether the folder uses inherited permissions or custom permissions. ## Use custom permissions If **Inherit permissions** is on, the folder follows permissions from its parent folder or section. Turn it off to set custom permissions for this folder. When you turn inherited permissions off, Falconer copies the current access into the folder. You can then update people, groups, and organization access directly. ## Add people or groups 1. Under **People with access**, enter a person's name or group name. 2. Select the person or group. 3. Use the permission menu next to their name to choose **Can view**, **Can comment**, or **Can edit**. To remove access, open the same permission menu and choose **Remove access**. ## Change organization access Use **General access** to choose what everyone in your Falconer organization can do with the folder. Folder sharing does not include **Anyone with the link**. Link access is managed on individual docs. ## How folder changes affect docs When you change custom permissions on a folder, the change applies to descendants that inherit from that folder. For example, if a folder gives your organization **Can view**, an inheriting doc inside that folder gives your organization **Can view** too. If that doc uses custom permissions, it keeps its own settings instead. # Plan doc access > Plan who should be able to view, comment on, edit, and share docs before you update permissions. Before you share docs broadly, decide who needs access and where that access should be managed. Folders help you manage access at scale. When a folder uses custom permissions, docs and folders inside it can inherit those settings automatically. ## Permission levels Falconer uses the same access levels for docs, folders, people, groups, and your organization. | Level | What it allows | | --- | --- | | **No access** | Cannot open the doc or folder | | **Can view** | Can read the doc or browse the folder | | **Can comment** | Can read and leave comments | | **Can edit** | Can edit, move, and share | Docs can also have authors. Authors help Falconer know who is responsible for a doc, including review and update notifications. Author status is separate from the access level shown in **People with access**. ## Decide where access should come from A doc or folder can get access from several places: - **People** -- specific teammates or external users - **Groups** -- connected groups from your organization - **Your organization** -- everyone in your Falconer organization - **Anyone with the link** -- link access for docs - **A parent folder or section** -- inherited permissions Falconer uses the highest access level someone receives from any source. For example, if your organization has **Can view** and a teammate is added directly with **Can edit**, that teammate can edit. ## Use folders for repeated access Inherited permissions let a doc or folder follow the access settings from the nearest parent folder or section. This is the default for new docs and folders. It keeps a folder tree easy to manage because changing a parent folder can update access for everything inside it that still inherits from that folder. When a doc or folder inherits permissions, its share dialog shows where those permissions come from. The individual access controls are read-only until you switch to custom permissions. ## Use custom permissions for exceptions Custom permissions let a doc or folder keep its own access settings. Use custom permissions when one doc needs a different audience than the folder around it, or when a subfolder should manage a smaller group of docs separately. When you turn off inherited permissions, Falconer copies the current effective access into the doc or folder. You can then edit the copied settings without changing the parent. ## Remember that folder permissions affect docs Folder permissions are ultimately for managing access to docs. If a folder has custom permissions, descendants that inherit from it use that folder's settings. Descendants with custom permissions keep their own settings. Changing a parent folder does not overwrite them. ## Check search and agent access Falconer search, Q&A, and agent answers only use docs the requesting user can access. If someone cannot open a doc, Falconer does not surface that doc in answers or search results for them. # Share a doc > Give the right people access to one doc, manage authors, and control link access. Use doc sharing when one doc needs its own audience, authors, or link access. ## Open doc sharing 1. Open the doc. 2. Type **/Share** anywhere in the editor. Or Click **... -> Share** in the top right. The share dialog shows whether the doc uses inherited permissions or custom permissions. ## Use custom permissions If **Inherit permissions** is on, the doc follows permissions from its parent folder or section. Turn it off to set custom permissions for this doc. When you turn inherited permissions off, Falconer copies the current access into the doc. You can then update people, groups, organization access, and link access directly. ## Add people or groups 1. Under **People with access**, enter a person's name, email address, or group name. 2. Select the person or group. 3. Use the permission menu next to their name to choose **Can view**, **Can comment**, or **Can edit**. To remove access, open the same permission menu and choose **Remove access**. ## Change general access Use **General access** to choose broader access for the doc. - **Your organization** controls access for everyone in your Falconer organization. - **Anyone with the link** controls whether people with the doc link can open it. For link access, docs can be set to **No access** or **Can view**. ## Manage authors Authors are responsible for the doc. Falconer uses authors for doc review and update notifications. To add an author, search for a teammate in the **Author** section. To remove an author, click the **x** next to their name. Only organization members can be authors. ## Copy a share link Click **Copy share link** in the share dialog to copy the doc URL. The link does not grant access by itself unless **Anyone with the link** allows it. People who do not have access will need permission before they can open the doc. # Troubleshooting access > Answers to the most common surprises about who can see, find, and edit your docs. Permissions in Falconer usually do exactly what you expect. The questions below cover the few cases that surprise people, so you can tell intended behavior from a real problem.

I restricted a doc, but it still shows up in search

Search and agent answers use the broadest access a doc has from any of its locations. If a doc is reachable from one place that is still open to your organization, it stays findable for the people who can reach it that way, even if another location is locked down. This is intended. To fully restrict a doc, make sure every place it lives has the access you want, not just the one you were looking at.

I moved a doc or folder and now different people can see it

When an item uses inherited permissions, it follows the access of wherever it currently sits. Moving it into another folder makes it inherit that folder's access, so who can see it can change even though you never opened the share dialog. If you want an item's access to stay the same no matter where it lives, switch it to custom permissions before or after moving it. See [Choose inherited or custom permissions](/docs/use-cases/manage-permissions/choose-inherited-custom-permissions/).

I gave my whole organization access, but an external collaborator still can't open the doc

"Your organization" access only applies to members of your Falconer organization. Guests and external collaborators are not members, so they do not get access from that setting. To give an external person access, add them directly under **People**, or turn on **Anyone with the link** for the doc.

Why can everyone in my organization edit my new doc?

New docs and folders use inherited permissions by default, and they inherit from wherever you create them. A doc created in a shared company location inherits that location's access, which by default lets your whole organization edit. "New" does not mean "private," and "inherited" can mean "anyone can edit" depending on the location. To restrict a doc, switch it to custom permissions and set the access you want, or create it in your private docs first.

The sharing controls are greyed out and I can't change who has access

That doc or folder is using inherited permissions, so its access comes from a parent folder or section. The individual controls are read-only until you switch to custom permissions. Turn off inherited permissions to make the item keep its own settings. Falconer copies the current access in so nothing changes until you edit it. You also need edit access to change sharing in the first place.

I can't remove the last person with edit access

Every doc and folder needs at least one person who can edit it, so Falconer blocks a change that would leave it with no editor. Add another editor first, then remove the original one.

An old doc I never shared is visible to my whole organization

Docs created before inherited permissions existed can resolve their access from where they live. If such a doc sits in a shared company location and was never given its own access settings, it can inherit that location's organization-wide access. To fix it, open the doc, switch it to custom permissions, and set the access you want. If you have many older docs to review, contact support and we can help you audit them.

# Create skill docs > Turn Falconer documents into reusable skill docs that give Falcon instructions for repeatable workflows. A skill doc is a normal Falconer document marked as **Type: Skill**. Use skill docs for repeatable instructions, checklists, review flows, and team-specific workflows. ## When to create a skill doc Create a skill doc when your team has a workflow that should run the same way every time, such as: - Generating a weekly report from pull requests, meetings, memories, and recent messages in a named public Slack channel - Reviewing a rollout plan against your team's launch checklist - Writing release notes in your team's preferred format - Turning incident notes into a postmortem - Checking a draft against an internal style guide - Summarizing customer feedback with a standard set of themes Skill docs work best when they are specific. Instead of writing a broad doc like "How to write good docs," write a focused skill like "Generate weekly report." ## Write the skill Start by creating a regular Falconer document. Give it a clear title that describes the workflow. A useful skill doc usually includes: - **When to use it** -- the task or situation the skill is for - **Inputs** -- what Falcon should look at before doing the task - **Steps** -- the checklist or process Falcon should follow - **Output format** -- how Falcon should structure the response or draft For example: ```markdown # Generate weekly report Use this skill when writing a weekly team report for a specific date range. Before writing, search for relevant pull requests, meeting notes, stored memories, and recent messages in the named public Slack channel that Falcon has joined. Include: - shipped work - in-progress work - blockers or risks - important decisions - follow-ups for next week Respond with: 1. A short executive summary 2. Bullets grouped by theme 3. Links or citations to the source material Falcon used ``` ## Mark the doc as a skill After you write the document, mark it as a skill: 1. Open the document in Falconer. 2. Click the more button in the top-right corner. 3. Select **Details**. 4. In **Properties**, open the **Type** menu. 5. Select **Skill**. You need edit access to the document to change its type. If you do not see **Skill** as an option, skill docs may not be enabled for your organization. ## Share and maintain the skill Skill docs use normal Falconer document permissions. To share a skill with more teammates, update the document's sharing settings or publish it where the right people can access it. To update a skill, edit the original document. Falcon uses the latest version the next time someone references it. To stop using a document as a skill, open **Details**, change **Type** back to **Document**, or archive the document. To reference a skill in chat, see [Use skill docs](/docs/use-cases/skill-docs/use-skill-docs). # Use skill docs > Reference skill docs in Falconer chat to give Falcon reusable instructions for repeatable work. A skill doc is a normal Falconer document marked as **Type: Skill**. Use skill docs to give Falcon repeatable instructions, checklists, review flows, and team-specific workflows. When you reference a skill in Falconer chat, Falcon reads the skill doc's Markdown and uses it as context for the current task. ## Use a skill in chat You can use a skill from Falconer chat on the homepage or in the document editor. 1. Open Falconer chat. 2. Click **+** and select **Skills**. Or, type **/** and start searching for the skill by name, such as `/Gen`. 3. Select the skill. 4. Add the task you want Falcon to complete. For example, after selecting **Generate weekly report**, add the date range: ```markdown for week of May 24 ``` The selected skill appears as a reference in your message. Falcon receives the skill doc's Markdown as context, then follows the workflow described in the skill. For the weekly report example, Falcon searches pull requests, meeting notes, memories, and recent messages in the named public Slack channel before drafting the report. ## Skill access People can only find and use skill docs they can view. If a skill does not appear in the picker, ask the document owner to update the document's sharing settings or publish it where the right people can access it. Falcon uses the latest version of the skill doc each time someone references it. To make a reusable skill, see [Create skill docs](/docs/use-cases/skill-docs/create-skill-docs). # Write a doc > Write with AI, with your sources as context, or start from a blank slate. Write with AI, with your sources as context, or start from a blank slate. Falconer's editor combines rich text formatting with AI assistance. Reference your code, tasks, and existing docs while you write -- and use inline AI to handle the grunt work. ## Create a document Click the **+** icon in the sidebar to create a new document. It starts in your Private collection. You can publish it to your Company documents for all to see, or share it more granularly with the Share button. ## Write in the editor Type **/** to open the command menu for quick formatting, like highlighting a passage and editing it with the agent. ## Reference sources Type **@** anywhere in the editor or in the agent chat to pull in context from your connected sources. - **@ documents** -- Link to other Falconer docs. Hover over a reference to preview its content. - **@ code files** -- Tag specific files or repositories from GitHub. - **@ Linear tasks** -- Reference tasks and project context. - **@ people** -- Mention teammates by name.    # Write a doc from Slack > Turn any Slack conversation into a structured Falconer document. Turn any Slack conversation into a structured Falconer document. ## Prerequisite Slack is connected to your Falconer org. ## Steps 1. Mention `@Falcon` in a Slack thread with a request like "write a new doc for this" 2. The bot analyzes the conversation thread, extracts context, processes any images, and creates a formatted document 3. Access the generated document via a link in Falcon's response, then refine it using Falconer's editing tools ## Tips - **Provide clear instructions** -- Specify what you need, whether that's creating documentation, summarizing discussion, or recording decisions - **Refine before sharing** -- New documents appear in a private collection initially, allowing revision before team distribution - **Leverage updates** -- Beyond initial creation, Falcon can modify existing documents based on subsequent Slack conversations