# Readit Documentation Welcome to the official documentation for Readit. This guide provides everything you need to understand and use Readit to inject powerful, portable context into your AI agents. ## getting-started # Introduction This section provides a high-level overview of what Readit is, its core principles, and how you can get started in seconds. ## What is Readit? Readit is a **Context Injection System for AI Agents**. It allows you to package all the necessary context for a taskβ€”instructions, reference documents, prompts, and even dynamic data sourcesβ€”into a simple, portable Markdown link called a "Readit." When an AI model consumes a Readit link, it uses the provided Markdown as its complete operating context. This solves critical problems in working with LLMs: > - **Minimizes Hallucinations:** By providing a clear and bounded context, the model is less likely to invent facts or go off-topic. > > - **Ensures Reproducibility:** The same Readit will produce consistent outputs across different agents and sessions. > ## Mental Model A Readit is a *context bundle*: instructions + references + links + dynamic assets. An agent fetches it as raw Markdown and uses it as operating context for a task. ## Key Principles Readit is built on three core principles: - **Stateless & Ephemeral:** Readits are designed to be loaded, used, and forgotten. There's no persistent state on the agent's side. Links can even have a Time-To-Live (TTL) for temporary access. - **Markdown-based:** Simplicity is key. Using Markdown makes Readits easy to create, read, edit, and version-control using familiar tools. - **Secure:** Share your contexts confidently. Use public links for open documentation or tokenized links for private and unlisted content that you control. ## Basic Usage ``` # Paste this alongside your AI prompt: https://readit.md/your-token/my-context # The AI will automatically load and use the context ``` **Example prompt:** ``` Please review this code following the guidelines here: https://readit.md/abc123.../code-review-standards [Your code here] ``` # Anatomy of a Readit A Readit is more than just a single file. It's a container for a collection of contextual components: - 🧠 **System Instructions:** The main Markdown file that sets the rules, personality, and primary instructions for the AI agent. - πŸ“ **Additional Markdown Files:** Reference documents, FAQs, data sheets, or any supplementary material the agent might need. - πŸ’¬ **Saved Prompts/Notes:** Reusable prompts or notes that can be referenced or embedded. - πŸ”— **Dynamic Sources & Links:** Links to external commands or API endpoints that the agent can be instructed to use. - **Commands**: like search or push information endpoint ## Creating Readits Writing Effective System Instructions: ```markdown # AI Assistant Context ## Role You are a senior code reviewer with expertise in Python and best practices. ## Guidelines - Focus on security, performance, and maintainability - Suggest specific improvements with code examples - Be constructive and educational in your feedback ## Code Standards - Follow PEP 8 style guidelines - Use type hints for function parameters - Include docstrings for all public functions ``` ## File Management **Organizing Multiple Files:** ``` my-context/ # Your readit β”œβ”€β”€ main.md # Main system instructions β”œβ”€β”€ guidelines.md # Detailed guidelines β”œβ”€β”€ examples.md # Code examples β”œβ”€β”€ faq.md # Common questions └── ... ``` **Linking internal Files:** ```markdown For detailed examples, see [examples.md](https://readit.md/gi0wQgl6GoFx37MY/readit-docs/./examples.md) ``` **Linking other readit Files:** ```markdown For dependencies, see [libraries](https://readit.md/gi0wQgl6GoFx37MY/readit-docs/my-docs/libraries.md) ``` **External Resource Links:** ```markdown ## Current Standards - [Company Style Guide](https://company.com/style) - [Security Checklist](https://security.company.com/checklist) ``` ## The Root File You can designate one file as the "main" or "root" file. This is the file that will be served when someone accesses the Readit's base URL (e.g., `.../`) without specifying a filename. ## Accessing Specific Files Append the filename to any Readit URL to get the raw Markdown content of that specific file. https://readit.md///.md # Visibility Levels You have full control over who can access your content. ## Public Public Readits are open to the world. They are ideal for documentation, guides, educational content and prompts. - URL Format: `https://readit.md//` - Indexable by search engines. - Visible in public directories. For private personal use, "space-name" is your username. ## Unlisted Unlisted Readits are accessible only to those with the direct link. They are perfect for selective sharing with teams or collaborators, or for personal use when you want a link that doesn't expire. - URL Format: `https://readit.md//` - Not indexed by search engines. - Do not appear in public directories. - Access can be revoked by changing the token. ## Private Private Readits are for your eyes only. By default, they are inaccessible to anyone else and are perfect for personal notes, drafts, or sensitive information. However, you can share them with anyone for 60 minutes at a time - URL Format: `https://readit.md//` (via temporary share link) - Not indexable. - Temporary 1-hour share links can be generated. - You can extend expiration, revoke access, or regenerate the token at any time. ## Token Security Readit links use a secure token to protect access. - **Format:** URL-safe characters (a–z, A–Z, 0–9) - **Length:** Minimum 16 characters (~95 bits of entropy) - **Generation:** Created with a cryptographically secure random generator (CSPRNG) - **Validation:** Token must match both the random value and the associated slug - **Rate limiting:** Server enforces request limits to block brute-force attempts - **Storage:** Tokens are stored securely with database-backed lookups **Security note:** Brute-forcing a valid token+slug pair is computationally infeasible under these constraints. ## advanced-features # File Embedding (Transclusion) You can embed the content of one Markdown file directly inside another. This is useful for creating master documents or reusing content snippets. To embed a file, simply prefix a standard Markdown link with an exclamation mark (`!`). Markdown ``` This is the main document. Below is the embedded content from another file. ![FAQ Content](https://readit.md/a1b2c3d4.../my-docs/faq.md) The main document continues here. ``` The system will replace the link with the full raw Markdown content of `faq.md` during rendering. You can only embed files from Readits that belong to you. A "Copy Embed Link" option is available in each file's context menu. Cross-readit transclusion is allowed for files owned by the **same user** and permitted by visibility. ## Rendering Pipeline ``` Markdown content ↓ Transclusion (embed other files; cycle detection) ↓ resolve relative β†’ absolute path ↓ Liquid templating (variables, conditionals, loops) ↓ Raw Markdown output served to user/agent ``` **File Embedding (Transclusion) :** ```markdown ## Faq ![FAQ Content](https://readit.md/a1b2c3d4.../my-docs/faq.md) ``` see here about it [Transclusion](https://readit.md/gi0wQgl6GoFx37MY/readit-docs/...) ## When to Use - Factor long docs into smaller files - Share a canonical snippet across multiple readits ## Checklist - [ ] Prefer transclusion for reusable blocks - [ ] Avoid deep nesting (harder to maintain) - [ ] Verify visibility alignment across embedded files - [ ] Consolidate small, reusable snippets via transclusion - [ ] Prefer concise, model-ready formatting # Templating Engine Make your Readits intelligent and dynamic using the built-in templating engine. Readit processes **all** content through the Liquid templating engine before serving it. This means you can use variables and logic in any file, at any time, to generate dynamic Markdown. This allows you to insert the current timestamp, dynamically list all files in a Readit, show conditional content based on sharing status, variables, transformation and much more. We use Liquid syntax, see here for all details [shopify/liquid](https://shopify.github.io/liquid/) ## Complete Template Variable Reference The following variables are available for each readit rendering ### Time Variables - `{{ now }}`: Current ISO timestamp (e.g., "2025-09-17T18:30:00.000Z"). you can get different format using Date filter (see below) ### Readit Variables - `{{ readit.name }}`: The name of the Readit. - `{{ readit.description }}`: The Readit's description (can be null). - `{{ readit.slug }}`: The URL slug for the Readit. - `{{ readit.visibility }}`: Visibility level ("public", "private", "unlisted"). - `{{ readit.mainfile }}`: The name of the root file (can be null). - `{{ readit.files }}`: An array of all file objects in the Readit. - Each file object contains: `id`, `name`, `fileType`, `sizeBytes`, `tokenCount`, `summary`, `createdAt`, `updatedAt`. ### Current File Variables - `{{ file.name }}`: The name of the file currently being viewed. - `{{ file.token_count }}`: Token count of the current file. - `{{ file.size_bytes }}`: Size in bytes of the current file. ### Sharing Variables - `{{ url_token }}`: The sharing token for the current URL. - `{{ expired }}`: A boolean (`true`/`false`) indicating if the link has expired. - `{{ expires_in }}`: The number of seconds remaining before expiration (null if no expiration). ### Search Variables These are only available when the `?q=` parameter is in the URL. - `{{ search.results }}`: An array of result objects. - `{{ search.total }}`: Total number of results found. - `{{ search.query }}`: The search query string used. - `{{ search.limit }}`: The results-per-page limit. - `{{ search.offset }}`: The pagination offset. - Each result object contains: `id`, `filename`, `file_type`, `created_at`, `updated_at`, `rank`, `snippet`. ## Control flow and iteration you can use several control flow constructs and iterators: if/elseif/else, case/when, unless, for loop, cycle, tablerow... ###### if ``` {% if product.title == "Awesome Shoes" %} These shoes are awesome! {% endif %} ``` ###### for ``` {% for product in collection.products %} {{ product.title }} {% endfor %} ``` ## Filters These are the main filters that can be useful in a readit. ###### prepend ``` {{ "/my/fancy/url" | append: ".html" }} --> /my/fancy/url.html ``` ###### capitalize ``` {{ "title" | capitalize }} --> Test ``` ###### date ``` {{ now | date: "%a, %b %d, %y" }} --> Fri, Sep 19, 25 ``` ###### default ``` {{ product_price | default: 2.99 }} ``` ###### size ``` {{ "Ground control to Major Tom." | size }} ``` ###### truncate ``` {{ "Ground control to Major Tom." | truncate: 20 }} --> Ground control to... ``` ###### url encode ``` {{ "Tetsuro Takara" | url_encode }} --> Tetsuro+Takara ``` ###### Unique ``` {% assign my_array = "ants, bugs, bees, bugs, ants" | split: ", " %} {{ my_array | uniq | join: ", " }} --> ants, bugs, bees ``` ###### first ``` {{ "Ground control to Major Tom." | split: " " | first }} ``` ###### join ``` {% assign beatles = "John, Paul, George, Ringo" | split: ", " %} {{ beatles | join: " and " }} --> John and Paul and George and Ringo ``` For all filters, you can see here [shopify/liquid](https://shopify.github.io/liquid/) # Implementing Search in Your Readits The search functionality is a powerful feature powered by the templating engine. **How it Works:** Trigger a full-text search across all files within a Readit by adding the ?q= query parameter to any file URL. `https://readit.md///instructions.md?q=calendar` **The Search Result Object:** When the q parameter is present, a search object is made available to the template. It is not returned as a JSON response. ``` { "search": { "results": [ { "id": "string", "filename": "string", "file_type": "string", "created_at": "string (ISO 8601)", "updated_at": "string (ISO 8601)", "rank": "number", "snippet": "string" } ], "total": "number", "query": "string", "limit": "number", "offset": "number" } } ``` **Example: Rendering Search Results** You can use Liquid syntax inside your Markdown file to format and display the search results dynamically. ``` {% if search.total > 0 %} ## πŸ”Ž Found {{ search.total }} results for "{{ search.query }}" {% for result in search.results %} ### {{ result.filename }} {{ result.snippet }} [Open file](https://readit.md/{{ url_token }}/{{ readit.slug }}/{{ result.filename }}) {% endfor %} {% else %} _No results found for "{{ search.query }}"._ {% endif %} ``` ## Semantic search coming soon ## use-cases # Use Cases for Context Injection This page highlights practical scenarios where users benefit from injecting large amounts of context into ChatGPT (or any LLM). Context injection ensures the model operates with complete, accurate information, reducing hallucinations and making outputs more relevant. --- ## Engineering & Development ### Debugging Legacy Code Provide full code snippets (200+ lines) and error logs to identify the exact source of bugs in old systems. ### Code Migration Inject legacy code (e.g., PHP 5) alongside new framework docs (e.g., Laravel 11) to generate a reliable migration plan. ### Open Source Project Maintenance Supply GitHub issues, PR comments, and contributor feedback to analyze recurring pain points in a project. ### Incident Post-Mortem Feed system logs, dashboards, and ticket histories to reconstruct a failure timeline and generate prevention strategies. --- ## Legal & Compliance ### Contract Review Paste full service agreements plus internal policy documents to detect mismatches and risks. ### Legal Discovery Inject hundreds of pages of case evidence, emails, and contracts to extract timelines and highlight key mentions. ### Court Case Simulation Provide case files, witness statements, and precedent rulings to simulate a trial environment for training or study. --- ## Business & Enterprise ### Knowledge Base Assistant Inject product manuals and FAQs so employees or customers can query policies and procedures directly. ### Competitive Analysis Combine feature comparisons, competitor sites, and customer feedback to identify differentiators and weaknesses. ### Supply Chain Optimization Provide supplier contracts, shipping logs, and cost sheets to highlight bottlenecks and cost-saving opportunities. ### Enterprise Architecture Audit Upload system diagrams, vendor contracts, and security reports to assess risks like vendor lock-in. --- ## Research & Academia ### Research Paper Drafting Combine a long draft with reviewer comments to get context-aware editing suggestions. ### Literature Review Paste multiple paper abstracts or notes to summarize schools of thought and knowledge gaps. ### Grant Proposal Writing Inject funding guidelines, prior proposals, and research summaries to create a compliant draft. --- ## Healthcare & Psychology ### Medical Case History Provide patient notes, test results, and prior treatments to surface overlooked causes or summaries. ### Long-term Therapy Notes Inject months of session notes to detect recurring patterns and progress over time. --- ## Creative & Media ### RPG Game Mastering Paste character sheets and session logs to generate consistent new adventures. ### Creative Continuity Inject entire book chapters to draft the next installment while keeping characters and tone consistent. ### Documentary Script Writing Provide interview transcripts and archival notes to draft narration scripts for film or podcasts. ### Museum Exhibit Guide Inject artwork descriptions, artist bios, and floor plans to generate a visitor-friendly script. --- ## Communication & Collaboration ### Customer Support Summarization Provide long email chains to summarize customer issues and suggest the next best step. ### Team Project Context Inject meeting transcripts, Jira tickets, and Slack logs to surface recurring blockers. ### HR Performance Review Supply an employee's project history, goals, and feedback notes to generate a balanced review. --- ## Marketing & Content ### Campaign Analysis Inject newsletters, social posts, and performance data to identify which messages resonated most. ### Translation with Glossary Provide full manuals plus a controlled glossary to ensure accurate, consistent translations. ### Election Debate Prep Combine past speeches, opponent stances, and polling data to prepare rebuttals. --- ## Specialized Use Cases ### Documentation Drift Detection Feed system instructions and relevant documentation chunks to detect mismatches between docs and implementation. ### Financial Analysis Provide large transaction datasets to spot anomalies, trends, or risk areas. --- ## Why Context Matters Large context injection is useful when: - The answer depends on multiple long documents. - Accuracy requires cross-referencing facts. - Continuity is critical (e.g., story, legal, or medical cases). - Summarization or synthesis must reflect the *whole picture*, not fragments. Readit enables this by packaging instructions, documents, and prompts into portable Markdown links that LLMs can consume as a single source of truth. # Guidelines as a Single Source of Truth > The company maintains a **single source of truth** (a Readit with the latest guidelines). Whenever an employee, manager, or system uses ChatGPT (or any LLM) to analyze something, they simply **attach the guideline link**. The model then checks the content (contract, doc, code, etc.) _against the official policy_. --- **Executive Summary** Every company runs on guidelines β€” security rules, contract playbooks, HR policies, brand tone guides. The problem: policies change often, but teams still rely on outdated PDFs, memos, or tribal knowledge. Readit solves this by turning policies into **living, linkable sources of truth**. A single Readit holds the guideline, and every workflow β€” from pull requests to contract reviews to expense approvals β€” simply injects that link. Whenever the policy changes, the update is instant across all teams. This keeps development, legal, HR, finance, and customer-facing teams aligned, consistent, and compliant β€” without reshipping documents or retraining staff. --- Here are a few **1-sentence tagline options** you can use for a website hero section: 1. **"One link, always up to date β€” your company guidelines as a living source of truth."** 2. **"Stop shipping PDFs. Start injecting policies directly into every workflow."** 3. **"Readit keeps your teams aligned by making guidelines instantly usable in code, contracts, and conversations."** 4. **"Update once, enforce everywhere β€” security, legal, HR, and beyond."** 5. **"The easiest way to turn company policies into action, not paperwork."** --- ## πŸ”§ Developer-Focused 1. **"Inject coding and security guidelines into every PR β€” always current, never outdated."** 2. **"One link to enforce code style, security, and architecture rules across all pipelines."** 3. **"Readit turns your dev playbooks into live compliance checks in CI/CD."** --- ## 🏒 Enterprise-Wide 1. **"From contracts to code, Readit makes company policies a single, living source of truth."** 2. **"Update once, enforce everywhere β€” legal, HR, finance, and engineering in sync."** 3. **"Stop chasing policy PDFs β€” Readit delivers the latest rulebook into every workflow."** --- **"Readit makes company policies a living source of truth β€” injected into every PR, contract, and workflow."** It connects the **technical** (PRs, pipelines) with the **enterprise-wide** (contracts, workflows), so both audiences see themselves in it. --- Companies run on rules, policies, and playbooks. The challenge is keeping every team aligned when those rules evolve. Readit makes this simple: **write your guidelines once, update them in one place, and inject them everywhere they are needed.** Instead of sending out new PDFs or retraining every team, a single Readit link acts as the **source of truth**. Whether in a pull request, a contract review, or an HR decision, the latest guideline is always applied automatically. --- ## How It Works 1. **Authoring:** Legal, HR, Security, or any team writes and maintains their guideline inside a Readit. 2. **Linking:** Other teams add the Readit link whenever they use ChatGPT (or another LLM) for analysis. 3. **Injection:** The model consumes both the document being analyzed and the guideline from the Readit. 4. **Compliance:** The AI checks for alignment, violations, or improvements based on the current policy. --- ## Department Use Cases ### Development & IT - **Secure Coding Compliance:** In pull requests, pipelines inject the *security coding guideline* Readit to check new commits for unsafe patterns. - **Infrastructure as Code:** Terraform or Kubernetes configs are reviewed against cloud security policies. - **Architecture Reviews:** System design docs are validated against company architecture standards. --- ### Legal & Compliance - **Contract Review:** Legal counsel maintains a *contract guideline* Readit. - Sales or procurement uploads a contract + attaches the Readit link. - AI checks for risks (liability, jurisdiction, SLA gaps) based on official rules. - **Policy Updates:** As GDPR, HIPAA, or SOC2 requirements change, only the Readit is updated β€” all future contract checks use the new rules automatically. --- ### HR & People - **Employee Handbook:** HR writes vacation, expense, and conduct policies into a Readit. - Managers ask: *"Can remote workers expense co-working spaces?"* β†’ AI answers from the handbook. - **Performance Reviews:** When summarizing employee performance, managers inject the *review guideline* Readit to ensure consistent evaluation. --- ### Finance & Procurement - **Expense Validation:** Employees attach the *expense policy* Readit when submitting reimbursements. - AI verifies compliance before approval. - **Vendor Risk Checks:** Procurement uploads supplier proposals and injects the *vendor risk guideline* Readit to highlight missing certifications or red flags. --- ### Marketing & Communication - **Tone of Voice Enforcement:** Campaign drafts are reviewed against the *brand voice guideline* Readit. - **Crisis Response:** Communications teams inject the *PR playbook* when drafting responses to ensure alignment with official stance. --- ### Operations & Safety - **Workplace Safety:** Field reports are validated against the *safety procedures* Readit. - **Emergency Protocols:** On-site staff ask ChatGPT for guidance, and answers are drawn directly from the official safety Readit. --- ### Sales & Customer Success - **Pricing & Discount Policies:** Sales proposals are checked against the *pricing guideline* Readit to prevent unauthorized discounts. - **Support Escalation:** Customer support agents use the *escalation policy* Readit to decide the right next step. --- ## Why Use Readit for Policies? - **Single Source of Truth** β†’ Update once, apply everywhere. - **Automatic Enforcement** β†’ PRs, contracts, and requests always pull the latest rules. - **Cross-Department Consistency** β†’ Developers, lawyers, HR, and sales all work from the same baseline. - **Future-Proof** β†’ As policies evolve, the AI instantly reflects the new rules. --- ## Example **Scenario:** The company updates its security guideline to ban storing secrets in environment variables. - Developer opens a PR β†’ pipeline fetches the *security guideline Readit* β†’ PR flagged if secrets appear. - Legal reviews a vendor contract β†’ ChatGPT checks if the SLA includes secret management obligations, using the same guideline. - HR updates onboarding β†’ new hires see the updated practice in their Readit-based training. **Result:** Everyone, across departments, operates with the same current truth β€” without emails, memos, or outdated PDFs. --- Readit turns policies and guidelines into **living documents**, always available, always enforced, always consistent. # Agentic Documentation Traditional product manuals and FAQs are static, hard to search, and quickly outdated. Readit makes documentation **agentic** β€” living, interactive, and always accessible inside any AI assistant. ## How It Works 1. **Publish a Public Readit** - The company writes product manuals, troubleshooting guides, and warranty information in Markdown. - This Readit is made public and linked directly from product packaging, datasheets, or websites. 2. **Share the Link** - Example: *"For interactive support, use: readit.md/abc123/manual"* - Customers can copy this link into any LLM (ChatGPT, Gemini, Claude, Grok, etc.). 3. **Ask Questions Naturally** - The LLM consumes the Readit as its context. - Customers type free-form questions such as: - *"How do I replace the filter?"* - *"What's included in the warranty?"* - *"Is this product compatible with model X?"* 4. **Get Authoritative Answers** - Responses are drawn directly from the official, most up-to-date Readit. - Customers don't need to dig through PDFs or outdated FAQ pages. --- ## Benefits - **Interactive Manuals** β†’ Documentation becomes a two-way conversation instead of static text. - **Always Up to Date** β†’ When the company updates the Readit, customers instantly access the new version. - **Cross-Platform** β†’ Works with all major LLMs, no integrations required. - **Reduced Support Load** β†’ Customers solve issues themselves, lowering the volume of tickets. - **Trust & Control** β†’ Answers come from the company's official source, not unreliable forums. --- ## Example Scenarios - **Electronics Manufacturer** - Public Readit includes setup guide, firmware updates, troubleshooting. - Customers ask: *"What's the maximum supported memory?"* - **Appliance Maker** - Public Readit includes maintenance steps and spare part numbers. - Customers ask: *"How often should I clean the filter?"* - **Software Vendor** - Public Readit includes API docs, integration guides, and license terms. - Customers ask: *"How do I authenticate with OAuth?"* - **Automotive Supplier** - Public Readit includes user manual and warranty policies. - Customers ask: *"What's covered under the 5-year warranty?"* --- ## Why "Agentic Documentation"? Unlike static documentation, **agentic documentation** turns manuals into an active participant: - It adapts to user queries. - It guides troubleshooting. - It evolves seamlessly as policies and features change. With Readit, documentation is no longer a PDF β€” it's an AI-powered, interactive experience. # Agent Context Hub for Software Teams Software companies often create custom AI agents to support specific products, workflows, or internal tools. These agents typically rely on a mix of prompts, guidelines, product knowledge, and APIs. Readit acts as a centralized, versioned context hub for each agent β€” making it easy to maintain, update, and deploy AI behavior across environments. --- ## Scenario * Your company builds internal or customer-facing AI agents (e.g., Support Assistant for Product X, Code Reviewer for Team Y, PR Template Generator, etc.). * Each agent needs a set of instructions, reusable prompts, and references (e.g., product docs, style guides, component libraries, changelogs). * You create a dedicated Readit for each agent, containing all relevant context files. * Anywhere the agent runs β€” inside ChatGPT, in a CLI tool, or in a CI/CD pipeline β€” you inject the same Readit link to load its current behavior. --- ## Example: Code Review Agent Your engineering org defines a code review assistant with a dedicated Readit: ``` https://readit.md/abc123/code-review-agent ``` This Readit includes: * **main.md**: System instructions (role, style, expectations) * **standards.md**: Coding guidelines * **examples.md**: Annotated PR examples * **prompts/**: Reusable prompts for different types of reviews * **links.md**: References to external policies or tools In your CI pipeline or local tool: ```bash curl https://readit.md/abc123/code-review-agent > context.md ai-reviewer --context context.md --files src/ ``` The same agent instructions are used across: * GitHub Actions for PR automation * Local developer CLI tools * Manual usage in ChatGPT / Claude with [Paste your code + Readit link] --- ## Benefits * **🧠 Unified Agent Behavior** – Same instructions everywhere the agent is invoked * **πŸ” Reusable & Modular** – One Readit per agent, versioned and maintainable * **πŸš€ Faster Iteration** – Prompt engineers can update logic in one place * **πŸ›‘οΈ Enterprise Control** – Access levels (private, unlisted, public) + tokenized links * **πŸ“¦ Environment Agnostic** – Works in web UIs, terminals, pipelines, and custom apps --- ## When to Use * You're building internal or external AI agents tied to specific products * Each agent requires structured context (prompts, guidelines, templates) * You want to maintain context updates without hardcoding or duplicating prompts * You want AI behavior to be consistent across tools, teams, and environments --- ## Implementation Examples ### Customer Support Agent ``` https://readit.md/company/support-agent-v2 Files: β”œβ”€β”€ main.md # Core instructions and personality β”œβ”€β”€ product-knowledge/ # Feature docs, FAQ responses β”œβ”€β”€ escalation-rules.md # When to hand off to humans └── templates/ # Common response patterns ``` ### DevOps Assistant ``` https://readit.md/company/devops-assistant Files: β”œβ”€β”€ main.md # System role and capabilities β”œβ”€β”€ runbooks/ # Step-by-step procedures β”œβ”€β”€ troubleshooting.md # Common issues and solutions └── infrastructure.md # System architecture context ``` ### Documentation Generator ``` https://readit.md/company/docs-generator Files: β”œβ”€β”€ main.md # Writing style and format guidelines β”œβ”€β”€ templates/ # Documentation templates β”œβ”€β”€ examples.md # Well-written doc examples └── api-standards.md # API documentation conventions ``` --- ## Enterprise Workflow 1. **Create Agent Readits** – One per agent type (support, code review, docs, etc.) 2. **Version Control** – Update agent behavior by editing Readit files 3. **Deploy Everywhere** – Reference the same Readit URL across all tools and environments 4. **Monitor & Iterate** – Track agent performance and refine instructions as needed 5. **Access Control** – Use private links for internal agents, public for customer-facing ones This approach transforms scattered AI instructions into a centralized, maintainable system that scales with your organization's AI adoption. # Collaborative Context Hub for LLMs In this use case, Readit serves as a shared context hub where multiple team members can contribute, update, and access contextual information for a particular project, feature, or client. Each team member can use their preferred LLM toolβ€”like ChatGPT, Gemini, Claude, or Codexβ€”but they all share and enrich the same Readit link. --- ## How It Works ### 1. Starting the Context One team member begins by creating a Readit containing initial context and decisions. They use this Readit link while chatting with an LLM to analyze or brainstorm about the feature. ### 2. Collaborative Updates Another team member can take the same Readit link and continue the analysis in their LLM of choice. They add new insights or decisions back into the Readit, keeping the context up-to-date. ### 3. Development and Testing The developer can use the same Readit to understand the full context and make informed architectural decisions. They might also add technical notes or documentation back into the Readit once development is complete. ### 4. Support and Assistance The support team can access the same Readit to get all the relevant background information and provide more accurate assistance to users. ### 5. Easy Contribution Team members can quickly add information to the Readit by pasting a link to a chat, sending an email to a unique address for that Readit, or using a simple interface to append new notes. This makes it easy for anyone to keep the context fresh and complete. --- ## Example: Feature Development Lifecycle ### Initial Planning Phase **Product Manager** creates: ``` https://readit.md/team/user-dashboard-v2 Files: β”œβ”€β”€ main.md # Feature requirements and goals β”œβ”€β”€ user-research.md # Research findings and user feedback β”œβ”€β”€ competitive-analysis.md # Market analysis └── success-metrics.md # KPIs and success criteria ``` The PM uses this Readit with ChatGPT to refine requirements and explore edge cases. ### Design Phase **UX Designer** takes the same Readit link and adds: ``` β”œβ”€β”€ design-decisions.md # Design rationale and choices β”œβ”€β”€ wireframes.md # Links to design files β”œβ”€β”€ accessibility.md # A11y requirements └── user-flows.md # User journey mappings ``` The designer uses this enriched context with Figma AI or Claude to validate design decisions. ### Development Phase **Developer** accesses the full context and adds: ``` β”œβ”€β”€ technical-approach.md # Architecture decisions β”œβ”€β”€ api-design.md # API specifications β”œβ”€β”€ database-changes.md # Schema modifications └── implementation-notes.md # Development insights ``` The developer uses this comprehensive context with GitHub Copilot or Cursor AI. ### Testing & QA Phase **QA Engineer** uses the complete Readit to understand: - Original requirements - Design intentions - Technical implementation details - Known edge cases They add: ``` β”œβ”€β”€ test-strategy.md # Testing approach β”œβ”€β”€ edge-cases.md # Discovered edge cases └── bug-reports.md # Issues found during testing ``` --- ## Integration with Project Management Readit complements tools like Jira by serving as the central knowledge repository: - **Jira**: Tracks tasks, issues, and progress - **Readit**: Holds the living context that evolves with every conversation and decision ### Example Integration ``` Jira Epic: User Dashboard V2 β”œβ”€β”€ Readit Link: https://readit.md/team/user-dashboard-v2 β”œβ”€β”€ Task: Design wireframes β†’ Updates design-decisions.md β”œβ”€β”€ Task: Implement API β†’ Updates technical-approach.md └── Task: User testing β†’ Updates user-research.md ``` Each Jira task references the same Readit, ensuring everyone has access to the complete, evolving context. --- ## Collaboration Patterns ### Cross-Functional Alignment - **Marketing** uses the Readit to understand feature benefits for messaging - **Sales** accesses customer requirements and competitive positioning - **Customer Success** reviews the context for training and support preparation ### Knowledge Transfer When team members join or leave: - New joiners get instant access to complete project history - Departing members leave their insights captured in the Readit - No knowledge is lost in handoffs ### Multi-LLM Workflow ``` Team Member A (ChatGPT) β†’ Updates Readit β†’ Team Member B (Claude) ↓ ↓ Adds analysis to context ←———————————————————— Continues analysis ``` Each person uses their preferred AI tool, but everyone benefits from the shared, growing context. --- ## Benefits - **πŸ”„ Continuous Context Building** – Knowledge accumulates across all team interactions - **🀝 Cross-LLM Compatibility** – Works with any AI tool that accepts markdown input - **πŸ“ˆ Evolving Intelligence** – Context gets richer with each contribution - **🎯 Unified Understanding** – Everyone works from the same comprehensive information - **⚑ Instant Onboarding** – New team members get complete context immediately - **πŸ”— Tool Integration** – Links seamlessly with existing project management workflows --- ## When to Use - Multi-phase projects with handoffs between team members - Cross-functional features requiring input from multiple disciplines - Long-running projects where context needs to be preserved over time - Teams using different AI tools but needing shared understanding - Client projects where multiple stakeholders contribute insights - Knowledge-intensive work where decisions build upon previous discussions # Documentation Drift Detector The **Documentation Drift Detector** is a pipeline-oriented workflow that uses Readit to keep your documentation aligned with your code. It automatically checks if feature documentation is drifting away from the current implementation, and flags discrepancies during CI/CD runs. ## Overview Documentation drift occurs when code changes but the related documentation is not updated. This leads to outdated guides, broken onboarding, and incorrect assumptions for developers. The Drift Detector ensures that your docs remain a reliable source of truth by continuously validating them against the latest commits. ## How It Works ### Pipeline Trigger On every commit or pull request, the pipeline calls a dedicated Readit link for drift detection. ### Context Assembly Readit bundles: - System instructions for the Drift Detector agent - Relevant documentation chunks (queried by feature or module, using ?q=...) - The changed code under review ### Agent Analysis The agent checks for: - **Outdated references** (code behavior no longer matches docs) - **Missing updates** (new functions/features not covered in docs) - **Contradictory information** (examples or explanations that no longer apply) ### Pipeline Feedback - βœ… If aligned: the pipeline passes silently. - ⚠️ If drift is detected: a comment is added to the PR with suggested doc updates. ## Example Setup ### Readit Link ``` https://readit.md/${{ secrets.READIT_TOKEN }}/doc-drift?q=user-auth ``` ### System Instructions (main.md) ```markdown # Documentation Drift Detection Agent ## Goal Verify that documentation for the selected feature matches the current implementation. ## Rules - Compare code behavior against documentation. - Flag outdated or missing explanations. - Suggest updated Markdown snippets when needed. - If everything is aligned, return βœ… "Docs are up to date." ``` ### Pipeline Integration (GitHub Actions) ```yaml - name: Run Documentation Drift Check run: | curl -sS "https://readit.md/${{ secrets.READIT_TOKEN }}/doc-drift?q=user-auth" \ -o context.md ai-reviewer \ --context=context.md \ --files=src/auth/*.js ``` ## Benefits - 🚦 **Continuous alignment** between code and docs - πŸ”Ž **Feature-aware validation** using Readit search filters (?q=feature) - 🧩 **Actionable output** with suggested Markdown patches - πŸ“œ **Reduced manual overhead** for keeping docs in sync ## When to Use - **CI/CD pipelines** – automatic doc checks on every commit/PR - **Feature branches** – validate that feature docs match the branch implementation - **Release workflows** – ensure docs are ready before tagging a release ## Next Steps - Combine the Drift Detector with [Changelog Automation](https://readit.md/gi0wQgl6GoFx37MY/readit-docs/../advanced-workflows.md) to auto-update release notes. - Use Readit's [Search Variables](https://readit.md/gi0wQgl6GoFx37MY/readit-docs/../templating-engine.md#search-variables) to target specific features or modules dynamically. # changelog-man-in-the-loop In many development workflows, changelogs are a necessary but often neglected artifact. They need to be clear, accurate, and timelyβ€”but writing them manually is tedious and error-prone. With Readit, changelog generation can be automated while keeping a human reviewer in the loop. ## The workflow As part of the CI/CD pipeline, a changelog can be programmatically created by analyzing commits, pull requests, or linked user stories. A language model (LLM) is used to transform this raw input into a structured Markdown summary that describes what changed. Once generated, this Markdown content is sent to Readit via API. The file is stored inside a dedicated Readit spaceβ€”for example, something like `acme-software-changelogs`. The POST response from the Readit API includes a direct link to the newly created file. This link is then shared with a product owner, project manager, or any human reviewer who’s responsible for reviewing the changelog. The reviewer opens the link and sees the draft in a clean, editable interface. They can refine the text, improve clarity, adjust the tone, or add missing context. Readit automatically tracks changes and preserves the updated content. Later, a scheduled pipeline step retrieves the reviewed fileβ€”using the same URL. It now contains the approved version, ready to be reused in the next steps: it may be published on a website, sent in a release email, or included in deployment metadata. ## Why it works This approach balances automation and human input: - The generation is fast, repeatable, and based on real data. - The review process is focused and lightweight, enabling human oversight where it matters. Readit acts as a central handoff point between machines and humans. The changelog is accessible, editable, and portableβ€”via a single URLβ€”making it ideal for reuse across pipelines and communications. ## Beyond changelogs This human-in-the-loop pattern is not limited to changelogs. It can be applied to release notes, technical documentation, weekly reports, or any content that benefits from being machine-generated and human-reviewed before publication. Readit enables these handoffs to happen smoothly, without context loss, version confusion, or email back-and-forth. ## integrations" # Integration Examples ## Popular AI Tools **ChatGPT / Gemini / Claude / Grok / DeepSeek / Qwen / Perplexity ... :** ``` Follow the guidelines here: https://readit.md/token.../guidelines [Your actual prompt] ``` **Custom Agents:** ```python import requests def get_context(readit_url): response = requests.get(readit_url) return response.text context = get_context('https://readit.md/token.../my-context') prompt = f"{context}\n\n{user_input}" ``` ## Development Workflows **CI/CD Integration:** ```yaml # GitHub Actions example - name: AI Code Review run: | curl https://readit.md/${{ secrets.READIT_TOKEN }}/code-review > context.md ai-reviewer --context=context.md --files=${{ github.event.pull_request.changed_files }} ``` **Code Review Contexts:** Create readits for different types of reviews: - `security-review` - Security-focused guidelines - `performance-review` - Performance optimization focus - `style-review` - Code style and formatting ## Advanced Workflows Readit can be integrated into more sophisticated development pipelines to enrich your AI workflows. ### Contextual Code Review with Search You can combine **Readit search** with your CI/CD pipeline to provide commit-specific context for AI reviewers: ``` https://readit.md/${{ secrets.READIT_TOKEN }}/code-review?q=commit-summary ``` This query injects contextual resources such as **related features, bug-fixing notes, or documentation snippets** directly into the review context. As a result, the AI can better understand the intent of the commit and maximize the quality of its feedback. ### Post-Pipeline Documentation Updates After a pipeline completes successfully, you can also use the **Readit Post API** to automatically append information to your documentation. This enables you to: - Track each commit or merge request in a structured Readit. - Keep your codebase documentation continuously updated. - Provide a historical context log for future reviews and audits. **Example Flow:** 1. Run AI code review with commit-specific context. 2. On successful pipeline completion, push a summary to the corresponding Readit. 3. Over time, build a **commit-aware documentation hub** directly inside Readit. # **Post-Pipeline: Push commit info to Readit** ## cURL (plain Bash) ```bash # Required env vars # READIT_TOKEN= # READIT_SPACE= # READIT_SLUG= # READIT_API=https://readit.md/api/v1 COMMIT_SHA="${GITHUB_SHA:-$(git rev-parse HEAD)}" COMMIT_MSG="$(git log -1 --pretty=%B)" COMMIT_AUTHOR="$(git log -1 --pretty=%an)" COMMIT_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/commit/${COMMIT_SHA}" # Example payload: append a new entry to changelog.md (or create if missing) cat > payload.json <<'JSON' { "action": "append", // "append" | "upsert" | "replace" "target_file": "changelog.md", // where to write "heading": "## Commit Log", // optional: ensure section exists "content": "" } JSON # Inject dynamic values CONTENT="### ${COMMIT_SHA:0:7} β€” ${COMMIT_MSG//$'\n'/ } - Author: ${COMMIT_AUTHOR} - Link: ${COMMIT_URL} - Date: $(date -u +%Y-%m-%dT%H:%M:%SZ) " # Update JSON "content" field python - < Notes - > action can be append (add at end/under heading), upsert (create or update a block keyed by commit), or replace (overwrite file). - > If you support section targets, you can add "section": "## Commit Log" instead of heading. --- ## GitHub Actions (YAML) ```yaml name: CI on: push: branches: [ main ] jobs: build-and-doc: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Build & Test run: | echo "Run your build/test here" - name: AI Review (optional) run: | curl -sS "https://readit.md/${{ secrets.READIT_TOKEN }}/code-review?q=${{ github.sha }}" - name: Append commit info to Readit if: ${{ success() }} env: READIT_TOKEN: ${{ secrets.READIT_TOKEN }} READIT_SPACE: your-space-or-username READIT_SLUG: code-review READIT_API: https://readit.md/api/v1 run: | COMMIT_SHA="${{ github.sha }}" COMMIT_MSG="${{ github.event.head_commit.message }}" COMMIT_AUTHOR="${{ github.actor }}" COMMIT_URL="${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}" cat > payload.json <<'JSON' { "action": "append", "target_file": "changelog.md", "heading": "## Commit Log", "content": "" } JSON CONTENT="### ${COMMIT_SHA:0:7} β€” ${COMMIT_MSG//$'\n'/ } - Author: ${COMMIT_AUTHOR} - Link: ${COMMIT_URL} - Date: $(date -u +%Y-%m-%dT%H:%M:%SZ) " python - <<'PY' import json, os p=json.load(open('payload.json')) p["content"] = os.environ["CONTENT"] json.dump(p, open('payload.json','w')) PY curl -sS -X POST \ -H "Authorization: Bearer $READIT_TOKEN" \ -H "Content-Type: application/json" \ -d @payload.json \ "$READIT_API/readits/$READIT_SPACE/$READIT_SLUG/files" ``` --- ## Upsert a per-commit file (alternative) If you prefer one file per commit: ```shell curl -sS -X POST \ -H "Authorization: Bearer $READIT_TOKEN" \ -H "Content-Type: application/json" \ -d @- "$READIT_API/readits/$READIT_SPACE/$READIT_SLUG/files" <