# Account Handover URL: https://heykiku.com/glossary/account-handover A new account manager inherits a client the agency has held for three years. On the second call she asks which format the client prefers for monthly reports—a question the client already answered in year one, to someone who has since left. A week later she sends copy with a joke in it, not knowing the client's marketing director kills anything with humor on sight. Nothing here is a disaster on its own. But the client has now watched the agency forget two things it should already know, and the new account manager has no idea **she's already a step behind a relationship she just inherited.** This is what makes an account handover different from a generic internal exit-checklist. The departing account manager doesn't just hold tasks and logins—she holds three years of pattern recognition. Why the client rejected the bold rebrand concept in year two. Which stakeholder has to be CC'd or the work gets re-litigated. That the client says "make it pop" but means "make it calmer." **None of this lives in the PM tool, the CRM, or any handover doc**, because none of it was ever a task. It lived in one person's head, and that person is leaving. The damage from a bad handover is slow and deniable, which is exactly why agencies underinvest in it. The client doesn't fire you over one forgotten preference. They lower their estimation of you a little at a time until, at renewal, the relationship feels colder than the work justifies. By then nobody connects the churn back to the handover six months earlier. **The continuity the client is paying for is invisible right up until it breaks.** heykiku preserves that institutional context in a form the new account manager can query directly: the rejected concepts and why, the stakeholder who kills humor, the unspoken preferences built up over years. And because access is role-based, a freelancer brought in to cover the gap can see the working preferences and brand notes they need without ever seeing the commercial terms of the account. --- # Agency Capacity Planning URL: https://heykiku.com/glossary/agency-capacity-planning How many projects can your agency take on next month? Most founders answer with a gut feeling. Some check a spreadsheet that's already outdated. Few have real visibility into team availability, ongoing commitments, and the actual hours required for new work. This blindness creates **either underutilization or overcommitment**—neither is profitable. The cost of poor capacity planning compounds quickly. Say yes to too much, and quality suffers. **Teams burn out**. Deadlines slip. Clients who expected your A-team get stretched resources and B-minus work. Say yes to too little, and you're leaving revenue on the table while competitors scoop up the clients you turned away. The challenge is that capacity planning requires **information that's scattered everywhere**. Project timelines in one tool. Team schedules in another. Client expectations in email threads. Historical data on how long things actually take buried in invoicing systems nobody analyzes. Without consolidated visibility, capacity planning becomes guessing with confidence. Agencies that forecast accurately **make their knowledge accessible**. They track how long different project types actually take, not just how long they were quoted. They document team skills and availability in one place. They surface [utilization data](/glossary/utilization-rate) when scoping new work. When the information exists and is findable, capacity decisions become strategic instead of reactive. --- # Agency Knowledge Base URL: https://heykiku.com/glossary/agency-knowledge-base Every agency has knowledge. The question is **where it lives**. In email threads nobody can find? In Slack messages that scroll away? In the heads of people who might leave tomorrow? An agency knowledge base brings scattered information into one searchable place. The cost of not having a knowledge base is invisible until you measure it. Eight hours a week answering the same questions. Two weeks to onboard someone who should be productive in two days. **Critical context lost every time a team member moves on**. These aren't small inefficiencies—they're the difference between scaling and stalling. The challenge isn't knowing you need one. Every agency owner has said "we should document this" a hundred times. **The challenge is actually building it**. Traditional wikis require writing—the thing agency owners have no time for. They require maintenance—another task that never makes the priority list. They require discipline that creative teams rarely sustain. The agencies that succeed with knowledge bases are the ones that **make capture effortless**. Voice notes instead of writing. Automatic organization instead of manual filing. Answers that surface when people ask, not when they remember to search. When adding knowledge is as easy as explaining something once, the knowledge base actually gets built. --- # Agency Margins URL: https://heykiku.com/glossary/agency-margins Every agency owner knows their revenue. Fewer know their actual margins. The difference between billing $10,000 and keeping $3,000 versus $5,000 is the difference between building wealth and running a stressful job. **Margins are the truth that revenue obscures**. Margin erosion happens quietly. A project quoted at 40% margin becomes 25% after [scope creep](/glossary/scope-creep). A retainer that seemed profitable loses money once you account for unbilled client calls. A "quick favor" here and there adds up to **thousands in untracked work**. Most agencies don't realize they have a margin problem until cash flow gets tight. The challenge is visibility. Tracking margins requires knowing true costs—not just direct labor, but overhead allocation, revision time, and **the hidden hours that never make it to timesheets**. When this information is scattered across tools, spreadsheets, and people's heads, accurate margin calculation becomes impossible. Protecting margins starts with documentation. Clear scope definitions prevent creep. [Rate cards](/glossary/rate-card) ensure consistent pricing. Project templates capture all billable components. When your team can quickly reference what's included—and what isn't—they stop giving away work for free. **The agencies with healthy margins aren't charging more; they're leaking less**. --- # Agency Playbook URL: https://heykiku.com/glossary/agency-playbook "Wait, who signs off on client-facing copy before it goes out?" It's 11:47pm, the campaign launches in the morning, and the new project manager has been Slacking three different people for the last forty minutes trying to answer something that should have taken four seconds. Everyone on the team knows the answer. Nobody wrote it down. **That's what a missing playbook actually costs**: the small frictions that pile up into late nights, burnt-out people, and mistakes that don't show up on any dashboard. An agency playbook is the working understanding of how the business runs, made accessible to everyone who needs it. Not a brand document, not a values PDF — the actual knowledge: who approves what, how quotes get built, which clients bill monthly and which bill on milestones, why you stopped using a specific vendor six months ago, what "done" looks like for each type of [deliverable](/glossary/deliverable). **Everything a new hire would have to ask you if the playbook didn't exist.** The problem with most agency playbooks is that they're written once and abandoned. The agency grows, processes shift, the doc drifts out of date, and the people who need answers learn that asking the founder is faster than checking the wiki. Within six months, the playbook is decoration — and the founder is back to being the bottleneck every new question flows through. heykiku turns the playbook into something agencies actually use. Upload process docs, pricing logic, client histories, the reasoning behind past decisions — everything that would normally live in the founder's head — and anyone on the team can query it by asking a question instead of hunting through folders. Role-based access means freelancers get the parts that apply to their work without seeing internal commercial decisions. **The playbook stops being a document and starts being the answer to "how do we do things here?" — available in the moment someone needs it.** --- # Agency Positioning URL: https://heykiku.com/glossary/agency-positioning "We're a full-service marketing agency." **This positioning says nothing**. It means you compete with every other agency on price and availability. When you stand for nothing specific, clients have no reason to choose you over the hundred alternatives their Google search returned. The cost of weak positioning is paid in **wasted business development**. RFPs you shouldn't be responding to. Proposals that don't convert because you're not the obvious fit. Clients who hire you for one thing, then expect something else. Pricing pressure because you're interchangeable. Every symptom traces back to unclear positioning. The challenge is that **positioning requires saying no**. No to clients outside your niche. No to services that don't fit your expertise. No to the comfortable generalist identity that feels safer. Agencies struggle because strong positioning means turning down money today for better money tomorrow—and tomorrow's payoff isn't guaranteed. Clear positioning starts with **documented clarity**. Your ideal client profile, written down. Your specific value proposition, articulated. Your competitive differentiators, captured where your team can reference them. When positioning is documented and accessible, sales conversations stay on-message. When it's vague or scattered, every team member pitches a different agency. --- # Agency Tech Stack URL: https://heykiku.com/glossary/agency-tech-stack Every agency has a tech stack. **Most didn't design theirs; it happened**. Notion because someone liked it at a previous job. Slack because the first big client insisted. Figma because the lead designer refused to use anything else. Google Drive because it was free. Harvest for time tracking, QuickBooks for invoicing, a project management tool the team argues about every six months. The result is ten to fifteen tools that don't talk to each other. The problem isn't having many tools—it's that **knowledge fragments across them**. The brief lives in Notion. The approved assets live in Figma. The client history lives in email. The pricing decisions live in Slack. When a freelancer asks a question, finding the answer means searching four apps and asking two people. The stack is complete on paper and impenetrable in practice. Agencies usually respond by trying to consolidate—move everything to one platform, force everyone to the same tool. **It rarely works**. Designers want Figma. Writers want Docs. Project managers want the tool that matches how they think. Forcing uniformity breaks workflows, and shadow tools appear within weeks. The real problem isn't tool diversity; it's that knowledge can't be found across the tools you already have. heykiku sits across an agency's tech stack without replacing any of it. Upload the documents that hold agency knowledge—briefs, [brand guidelines](/glossary/brand-guidelines), [SOPs](/glossary/standard-operating-procedures), client history, past work—and one AI assistant answers questions from all of them, regardless of which tool they originally came from. Role-based access means freelancers can query the knowledge they need **without being added to your Notion workspace**. The stack stays the same; the knowledge becomes searchable. --- # Approval Workflow URL: https://heykiku.com/glossary/approval-workflow Client approval is rarely simple. The marketing manager loves it. The CMO wants changes. **The CEO overrides everyone at the last minute**. The legal team has concerns nobody anticipated. Without a documented approval workflow, you're navigating this maze blind every single time. Agency approval chaos is uniquely complex. You're not just managing internal sign-offs—you're **managing client organizations you don't control**. Different stakeholders in different timezones with different priorities and different levels of authority. The person who briefs you isn't always the person who approves. The person who approves isn't always the person who can override. The cost of unclear approval workflows shows up in [revision cycles](/glossary/revision-round). **Work gets approved by the wrong person**. Higher-ups see it later and demand changes. The timeline slips. The team scrambles. The client blames you for not understanding their process—even though they never explained it. Documenting approval workflows means capturing **the client's decision-making structure**, not just your internal process. Who needs to see what, in what order? Who has veto power? Who's a stakeholder versus a decision-maker? When this is documented upfront and accessible to your team, approval becomes predictable instead of political. --- # Archive Completed Projects URL: https://heykiku.com/glossary/archive-completed-projects Projects end, but **their value shouldn't**. The campaign strategy that worked brilliantly. The client feedback that shaped revisions. The approach that solved a tricky problem. All of this is useful for future work—if it's findable when you need it. Most agencies **archive by abandoning**. Projects finish, folders close, attention moves to the next deadline. Six months later, someone asks "didn't we do something similar for Client X?" and nobody can find it. The work exists somewhere in a maze of folders, but practically it's lost. The cost is invisible but real. Teams recreate work that already exists. New projects ignore lessons from past projects. Client relationships restart from zero when account managers change. **Each finished project is a missed opportunity** to build institutional knowledge. Effective archiving isn't just storage—it's **organization for retrieval**. Clear naming and tagging so past work surfaces in searches. Key decisions and outcomes captured, not just final files. [Retrospective](/glossary/retrospective) insights linked to the project they came from. When archives are searchable and useful, past work becomes an asset instead of digital clutter. --- # Asset Library URL: https://heykiku.com/glossary/asset-library Without an asset library, teams **waste hours hunting** through Dropbox folders, email attachments, and old project files for the right logo version. Multiply that time by every project, every client, every team member, and the cost becomes staggering. An asset library isn't just file storage—it's **organized, searchable, and current**. The difference between a folder full of files and an asset library is the difference between a pile of books and a library. One requires luck to find what you need; the other requires a few seconds. The challenge with asset libraries is maintenance. Files get added but not organized. Outdated versions don't get removed. Metadata and tagging fall behind. Soon the library becomes **just another messy folder**, and people go back to asking "does anyone have the new logo?" Effective asset libraries require ongoing curation. Clear naming conventions. Version control that retires old files. Tagging that enables search. When the library is trusted as **the [single source of truth](/glossary/single-source-of-truth)**, people use it. When it's unreliable, they work around it—and the inefficiency continues. --- # Brand Guidelines URL: https://heykiku.com/glossary/brand-guidelines A freelance designer joins a project on Monday and delivers the first banner on Thursday. It's using the old logo. Not wrong-logo-on-purpose wrong — just the version that was current eighteen months ago, still sitting in the shared drive folder where it was first uploaded. Nobody told the freelancer the client rebranded last summer. The current logo lives in a folder called "2025 refresh – FINAL" that the freelancer never opened, because nobody sends new contractors a map of the drive. **The client sees the banner, assumes the agency wasn't paying attention, and the account manager spends the next hour on damage control for a mistake that was structural, not careless.** This is the brand guidelines problem most agencies never name out loud: guidelines don't fail because they're missing. They fail because they're **not findable by the people who need them at the moment they need them**. The senior designer knows where the current logo lives. The freelancer doesn't. The strategist knows which fonts were approved last quarter. The junior copywriter drafting a deck doesn't. The knowledge exists. The path to it is broken. The usual fix is to centralize — one brand hub per client, everyone gets the link. Within three months, the hub is stale. The client updates their palette, the change arrives by email, and the hub doesn't catch the update. People stop trusting the hub, and the hunt for the current version starts all over again. heykiku solves brand guidelines as a retrieval problem. Upload the current rules, approved assets, [tone doc](/glossary/tone-of-voice), and the explicit pet peeves captured from past client feedback — then anyone on the team can ask for what they need in the moment they need it. "What's the current primary hex code?" "Does Client X allow em-dashes in body copy?" "Which logo version do we use on a dark background?" The answer comes from the most recently uploaded source, not the folder a designer bookmarked a year ago. Role-based access lets freelancers query the same source of truth as internal staff without landing in internal strategy docs. **The guidelines become as fast to check as they are to ignore.** --- # Change Order URL: https://heykiku.com/glossary/change-order Creative projects change. The client sees the first round and wants to go in a different direction. The campaign strategy shifts based on market feedback. The CEO has a new vision that invalidates approved concepts. **These aren't failures—they're the nature of creative work**. The question is whether changes get documented and billed. A change order formalizes what most agencies handle with a sigh and a "sure, we can do that." Instead of absorbing the pivot and hoping to reconcile later, a change order **documents exactly what's changing**, why the approved direction is being abandoned, and what the new scope costs. The client approves before new work begins. Without change orders, **creative pivots become margin killers**. The client didn't like the direction—so you do another round. They want to add a video that wasn't in scope—so you figure it out. They need everything faster because their launch moved up—so you scramble. Each accommodation seems reasonable. Together, they destroy profitability. The best change order processes acknowledge creative reality while protecting margins. They're quick enough that account managers actually use them. They document the client's request in their words. They make the cost clear before work starts. When change orders are standard practice, **pivots become revenue instead of resentment**. --- # Client Confidentiality URL: https://heykiku.com/glossary/client-confidentiality A freelance designer joins the team to help with Client A's rebrand. To do their job, they get a login to the shared workspace where the agency keeps its files. That same login also opens Client B's unreleased product roadmap, Client C's media budget, and a competitor teardown the agency ran for Client D last quarter. Nobody intended that. The freelancer wasn't snooping. But **the access was binary**, so context for one account quietly became visibility into every account — and the agency just breached three confidentiality agreements without anyone noticing. Client confidentiality is the promise an agency makes — sometimes in a signed NDA, often just implied by the relationship — that what a client shares stays inside the people who need it. Agencies hold genuinely dangerous material: campaigns that move markets when they leak early, forecasts that reveal a client's runway, competitive intelligence that would be valuable to the very competitors sitting in the next account folder. **The duty doesn't scale down because the team is small or the contractor is trusted.** A leak from a five-person studio carries the same legal and reputational weight as one from a hundred-person shop. The hard part is that the same people who create confidentiality risk are the people agencies depend on. Freelancers and contractors work across multiple clients — that's the model. A copywriter might be on three of your accounts and four of someone else's in the same month. **Trust isn't a control.** "We've worked with her for years" is not a defense when a client asks how a contractor on their account could also see a rival's pricing. Confidentiality has to be enforced by what the system allows people to open, not by everyone remembering to be careful. heykiku enforces confidentiality through four access tiers inside a single agency workspace—general, internal, sensitive, and owner-only—each mapped to a separate Mistral library, where users only receive the library IDs their role permits. The freelancer on Client A's rebrand queries the general and project material they're cleared for and never sees the sensitive forecasts or owner-only intel sitting in the same workspace. Confidentiality becomes structural: the boundary is in the tier, so **the contractor physically can't retrieve what they weren't granted, no matter how they phrase the question.** --- # Client Onboarding URL: https://heykiku.com/glossary/client-onboarding Client onboarding is both **high-stakes and high-repetition**. It's high-stakes because first impressions shape the entire relationship. A smooth, professional onboarding builds confidence. A chaotic, confusing one plants seeds of doubt that never fully go away. It's high-repetition because every client goes through it. Whatever problems exist in your onboarding process—forgotten steps, unclear communication, delayed access setup—you'll experience them over and over. **Small inefficiencies multiply** across every new client relationship. This combination makes onboarding one of the **highest-value processes to document**. A comprehensive onboarding checklist ensures nothing falls through the cracks. Templated communications maintain professional consistency. Clear handoff points between sales and delivery prevent dropped balls. The best onboarding processes feel effortless to clients while being highly structured internally. They don't require the founder's involvement for every new client. They work consistently whether it's your first client of the year or your fiftieth. When onboarding is **documented and accessible**, scaling becomes possible without sacrificing client experience. --- # Client Relationship History URL: https://heykiku.com/glossary/client-relationship-history Long-term client relationships are **built on context**. Remembering why they chose that approach two years ago. Knowing which stakeholder prefers detailed explanations versus bottom-line summaries. Understanding the history behind their current priorities. This context makes clients feel valued and work more effective. When relationship history lives in people's heads, **it walks out the door with them**. The account manager leaves, and suddenly nobody remembers why the client hates certain terminology. The senior strategist moves on, and the context behind years of positioning decisions vanishes. Clients feel the discontinuity, even if they can't name it. Most agencies track project deliverables but not relationship context. They know what they delivered in 2023, but not the conversations that shaped those deliverables. They have contact lists, but not documented preferences. **The transactional record exists; the relationship record doesn't**. Agencies that preserve relationship history **capture beyond the formal**. Key decisions and the reasoning behind them. Client preferences and communication styles. Stakeholder dynamics and political considerations. When this context transfers between team members and survives turnover, client relationships maintain continuity that competitors can't match. --- # Creative Brief URL: https://heykiku.com/glossary/creative-brief The designer opens Figma, re-reads the brief, and realizes nobody answered the question that actually drives the work: who is this for? The audience line says "decision-makers in mid-market SaaS." That's not an audience — that's a LinkedIn filter. Without knowing whether the person seeing the campaign is a skeptical CFO or an enthusiastic VP of marketing, the designer is guessing about tone, visual complexity, and whether the headline should be conservative or playful. **[Two rounds of revisions](/glossary/revision-round) later, the answer finally comes out on a status call: "It was for the CFO all along."** The creative brief is supposed to prevent exactly this — the wasted hours that come from teams guessing at context the client already holds. In practice, most briefs capture the wrong things. They list deliverables, timelines, and specs. They leave out the strategic details that actually drive creative decisions: which competitor ads the client hates and why, what the previous agency got wrong, how this work fits the wider business goal, which stakeholder quietly has veto power. **The information that would let a designer make confident judgment calls is the information that gets skipped.** Even when the brief captures the right things, it usually lives somewhere inconvenient. A Google Doc shared at kickoff. A Notion page only the account manager bookmarked. A PDF attached to the [SOW](/glossary/statement-of-work). When the designer needs to re-read it at 3pm on Wednesday to settle a disagreement with the copywriter, finding it takes longer than finishing the work — so they guess instead, and the guess usually misses. heykiku makes the brief the place the team actually checks, because checking is fast. Upload briefs as they're written and the full team — designer, writer, freelancer, QA — can query the strategic context in the moment a decision depends on it. "Who are we targeting again?" "What did the client say about the last campaign they signed off on?" "Are we allowed to use humor here?" The answer comes back in seconds instead of a Slack thread nobody wants to start. **The brief becomes the working reference it was always meant to be, instead of a kickoff artifact everyone filed and forgot.** --- # Deliverable URL: https://heykiku.com/glossary/deliverable "The deliverable" is the most consequential noun in any agency. It's what you're being paid to produce, what the client will judge, and what the team has to agree on before work starts. **Yet most agencies define deliverables too loosely**—"a landing page," "a social campaign," "a brand refresh"—and then wonder why the final work drifts from what the client expected. A well-defined deliverable includes more than the output itself. It specifies **format, scope, and what "done" looks like**. "A landing page" becomes "one responsive landing page with hero, three benefit sections, a testimonial block, and a lead form, delivered as Figma file plus HTML export, with two rounds of revisions included." The ambiguity that causes [scope creep](/glossary/scope-creep), mid-project disputes, and margin erosion **shrinks when the deliverable is specified** with this level of detail. But specification alone isn't enough. The knowledge required to produce a deliverable consistently—[brand guidelines](/glossary/brand-guidelines), past examples, client preferences, process steps—has to be **accessible to the freelancer, the designer, and the QA reviewer in the moment they need it**. When the designer has to Slack the founder to confirm the current tone of voice, the deliverable is delayed. When the freelancer can't find the brand guidelines, the first draft misses. When the QA reviewer doesn't know what past deliverables looked like, inconsistencies slip through. heykiku supports deliverable production by making the surrounding knowledge findable without a hunt. Upload brand guidelines, past similar work, client preferences, and process docs once, and anyone producing a deliverable—internal or freelance—can query the context they need to get it right on the first pass. Role-based access means freelancers get the deliverable-relevant knowledge without exposure to unrelated internal material. **The deliverable stops being the moment where every knowledge gap becomes visible.** --- # Discovery Call URL: https://heykiku.com/glossary/discovery-call The discovery call is where client relationships begin. It's your first chance to understand what the client really needs—not just what they think they want. It's also where **critical context gets captured, or lost forever**. Most agencies treat discovery calls as sales conversations. They are, but they're also **the first knowledge capture moment**. The goals discussed. The challenges mentioned. The preferences revealed. The concerns raised. All of this information matters for the work ahead—if it gets documented and made accessible. Too often, discovery call insights **stay in the salesperson's head** or get buried in CRM notes nobody reads. When the project kicks off weeks later, the team starts from scratch. "What did the client say about their goals?" "Did they mention budget constraints?" "Who are their competitors?" The discovery call answered these questions, but the answers are gone. Effective discovery calls include documentation habits. Notes that get shared. Key insights that transfer to project briefs. A clear handoff from sales to delivery. When **discovery information flows into project work**, clients feel understood from day one. --- # Document Agency Processes URL: https://heykiku.com/glossary/document-agency-processes The problem with documentation isn't that agencies don't know they need it. It's that documentation has been defined as a project: a dedicated block of time, a blank page, a writing task that competes with billable work. Framed that way, **it always loses**. Client work is urgent. Documentation is important but never now. The agencies that actually build documentation habits don't treat it as a separate task. They **capture at the moment of creation** — while they're explaining something to a new hire, doing a process for the first time, solving a problem they don't want to solve again. A two-minute voice note after a client call contains more useful context than a structured document written three weeks later from memory. The medium matters because it determines who participates. When documenting requires sitting down to write, only people who write well and have spare time contribute. When it requires speaking a thought aloud, **everyone contributes**. The best knowledge capture systems meet people where they work, not where documentation theory says they should work. The failure mode isn't missing documentation — it's documentation that exists but **can't be found**. Files in folders nobody navigates. Notes in a tool only one person checks. Processes written by one person in a format only they can parse. Capturing knowledge is only half the practice. The other half is making it accessible at the moment someone needs it, without requiring them to already know it exists. --- # Document Conflicts URL: https://heykiku.com/glossary/conflicting-documentation A freelancer on a discovery call quotes the client $8k for the package. Confident, professional, completely wrong—the rate moved to $12k two months ago. The old number was in a pricing doc on the shared Drive. The new number was in a Notion page the account team updated. Neither replaced the other; they just coexist, and the freelancer opened the one that came up first. **Now the account manager is on cleanup duty, explaining to a client why the price they were quoted yesterday isn't real.** That's a document conflict: two sources that contradict each other on the same fact, both still treated as current. It happens because agency knowledge doesn't live in one place. A rate lands in a Drive spreadsheet, gets revised in a Notion doc, and is also sitting in a PDF the founder emailed a client once and never thought about again. Each was right when it was written. Nobody flagged that they now disagree, because flagging a contradiction requires somebody to be holding both versions side by side—and nobody ever is. The damage is specifically a trust problem, and it's contagious. Quote the wrong price once and the client wonders what else is wrong. The freelancer who got burned stops trusting the docs and starts pinging the founder to confirm everything, which is exactly the bottleneck documentation was supposed to remove. **One unresolved contradiction doesn't just cause one bad quote—it teaches the team that the knowledge base can't be trusted, so they route around it.** heykiku doesn't referee which of two documents is right — agency knowledge has no oracle. What it does: documents live in one library with a review clock, and nothing the team can ask about got there without a person approving it. When two files disagree, a person still has to decide. The [review interval](/glossary/knowledge-decay) and the approval step are how that decision gets a place to happen, instead of waiting for a freelancer to quote the wrong number on a client call. --- # Freelancer Access Control URL: https://heykiku.com/glossary/freelancer-access-control Freelancers need context to do good work. Client [brand guidelines](/glossary/brand-guidelines). Project history. Process documentation. Without access to this information, they produce work that misses the mark. But giving freelancers access to everything—client contracts, pricing discussions, internal strategy—**creates risk you shouldn't accept**. The default approach is binary: either freelancers get a shared drive login and see everything, or they get nothing and constantly ask questions. **Neither works**. Full access exposes sensitive information. No access means your team becomes a bottleneck, translating every question between freelancer and knowledge base. Most agencies solve this with manual curation. Someone exports relevant files, strips sensitive details, sends them over. This works once. By the third project with the same freelancer, nobody remembers what they can see. Files get reshared. Context gets lost. **The overhead kills the efficiency** freelancers were supposed to provide. The right approach is **access levels built into how knowledge is organized**. General information freelancers need is accessible. Client-specific details require client project access. Internal strategy and pricing stay hidden. When access control is structural rather than manual, freelancers get what they need without someone playing gatekeeper. --- # Freelancer Brief URL: https://heykiku.com/glossary/freelancer-brief Freelancers are a productivity multiplier—until they deliver work that misses the mark. Then they become **a revision sink**, consuming more time than they save. The difference is usually the brief they received, or didn't. Internal team members absorb context passively. They sit in meetings, overhear discussions, see Slack conversations. Freelancers have **none of that ambient information**. Everything they know about a project comes from what you explicitly tell them. Assume they know nothing, and brief accordingly. The classic freelancer brief mistake is **sending files without context**. Here are the [brand guidelines](/glossary/brand-guidelines). Here's what we need. Figure it out. This approach produces work that's technically competent but strategically off. The freelancer delivers what was specified, but not what was actually needed. Effective freelancer briefs include **the why, not just the what**. Project objectives. Target audience. How this piece fits the larger campaign. What success looks like. Client preferences and pet peeves. This context transforms freelancers from order-takers into genuine collaborators who can make smart judgment calls. --- # Handoff URL: https://heykiku.com/glossary/handoff **Bad handoffs are where projects go to die**. A designer finishes their work, throws files over the wall to development, and moves on. A strategist briefs an execution team via email, assumes everything's clear, and disappears into another project. An account manager goes on vacation, leaving no notes about in-progress client conversations. Each of these scenarios creates the same problem: **lost context**. The receiving team doesn't have what they need. They make assumptions that turn out to be wrong. They deliver work that misses the mark. The handoff that saved ten minutes costs hours of rework. Effective handoffs require structure. A standard format for what information must transfer. Clear expectations for both parties. **Documentation that exists independently** of the person handing off. When handoffs are systematic, context doesn't depend on memory or availability. The test of a good handoff is whether **the work could continue if the original person vanished**. If it could, you've successfully transferred knowledge. If it couldn't, you've created a dependency that will eventually cause problems. --- # Institutional Memory URL: https://heykiku.com/glossary/institutional-memory Six months after the account lead who built Client X's retainer leaves, someone asks why the pricing is structured that way and nobody has an answer. The decision is still in effect. **The understanding that produced it is gone**. That's the moment an agency discovers it had [tribal knowledge](/glossary/tribal-knowledge), not institutional memory. Tribal knowledge is what one person knows. Institutional memory is what the agency knows. The difference matters because institutional memory **survives turnover**—it stays when Sarah leaves, when Mike moves to another firm, when the senior partner goes on sabbatical. Most agencies don't distinguish between the two. They document tasks (SOPs) and store files (shared drives) but they don't actually capture **context**—the reasoning behind decisions, the backstory of client relationships, the lessons from past mistakes. The cost shows up as repetition. Agencies rebuild systems from scratch because nobody wrote down why the original was designed that way. They re-pitch clients because nobody remembered the first pitch failed. They relearn the same difficult-client lessons every two years because the person who learned them last time moved on. **Every time you relearn something, you've already paid to learn it once**. heykiku is built for institutional memory because capture happens when knowledge is fresh. A voice note after a difficult call preserves the reasoning while it's still clear. A retrospective uploaded the day it happened keeps the nuance that fades within a week. With role-based access, institutional memory isn't just founder-level context—it's distributed across the team in a way that protects sensitive information while making critical history available to the people who need it to do their work. --- # Internal Documentation URL: https://heykiku.com/glossary/internal-documentation Internal documentation is everything your agency knows about itself. **It's the stuff you'd need to onboard a new co-founder**—not the marketing site, not the client work, but the real understanding of how the business actually runs. Which clients pay on time. Why you stopped using a particular vendor. How you handle the edge case that comes up twice a year. The problem with internal documentation isn't that agencies don't write anything down. Most do. What gets written down is almost always the wrong thing. The welcome packet is polished. The process doc is detailed. But the **actual running understanding of the business**—the notes that explain why, the context that tells new hires what to avoid—tends to live in people's heads and leave with them. Good internal documentation isn't formal. It's the Slack thread where a senior strategist explained the reasoning behind a pricing decision, captured before it scrolls away. It's the voice note an account manager recorded after a difficult client call. It's the retrospective observation that never made it into a doc because nobody had time to write it up cleanly. **The most useful internal knowledge is the messiest**—caught in the moment, not reconstructed later. heykiku treats internal documentation as a capture problem, not a writing problem. Speak a thought and it becomes searchable knowledge. Upload a messy retrospective and it becomes answerable queries. With role-based access, sensitive internal context—pricing logic, partner disputes, client frustrations—stays visible to leadership while general process knowledge reaches everyone who needs it. **Documentation becomes a byproduct of the work, not a task you owe yourself.** --- # Key Person Risk URL: https://heykiku.com/glossary/key-person-risk An account director quits in October. She held three of the agency's top five clients—not just the contracts, but the relationships, the unwritten process for how each account ran, and a decade of context about why things were done the way they were. The founder isn't worried at first; the work product is fine and the team is capable. Then, within sixty days, two of those three clients quietly reduce their retainers. The new contact is competent, but the clients say the same thing in different words: **"They don't really know us anymore."** One person's exit just put a measurable dent in revenue, and no replacement hire fixes it fast. This is concentration risk, and it's specific to small agencies. At a 5-to-20-person shop, roles aren't cleanly separated. The same person is often the relationship, the process, and the memory for a slice of the business—the **bus factor** for that account is one. When that one person leaves, you don't have a team holding a client. You have a single point of failure with a calendar invite. Key person risk is different from [tribal knowledge](/glossary/tribal-knowledge), even though they travel together. Tribal knowledge is the information problem—facts living in one head instead of a system. Key person risk is the business problem that information creates: **revenue, client trust, and continuity all routed through a person who can quit, burn out, or get poached.** Agencies obsess over client concentration—"no client should be more than 20% of revenue"—while ignoring that a single employee can be a bigger liability than any single client. The defense isn't cloning your best people or writing a manual nobody reads. It's making one person's knowledge available to the rest of the team before they're gone. heykiku de-risks a departure by keeping the key person's accumulated context—client preferences, process decisions, the backstory behind each account—queryable by everyone who needs it, so when they leave, the relationship and the know-how don't leave with them. --- # Kickoff Meeting URL: https://heykiku.com/glossary/kickoff-meeting The kickoff meeting is a **critical knowledge moment**. Decisions get made. Expectations get set. Context gets shared. Roles get clarified. In a well-run kickoff, everyone leaves aligned on what success looks like and how to get there. The problem is that kickoff meetings generate information that **rarely gets captured**. Decisions made verbally disappear into the ether. Action items get forgotten. Context shared by clients fades from memory. Two weeks later, someone asks "didn't we discuss that in the kickoff?" and nobody can remember the answer. A kickoff meeting without documentation is a **missed opportunity**. Notes, action items, and decisions should be captured during the meeting—not reconstructed from memory afterward. These artifacts become the reference point when questions arise later. The best kickoffs are **structured for knowledge capture**. A clear agenda that ensures all critical topics get covered. A designated note-taker. A standard format for sharing outcomes. When kickoff documentation is consistent and accessible, projects start stronger and stay aligned. --- # Knowledge Decay URL: https://heykiku.com/glossary/knowledge-decay A junior designer pulls the [brand guidelines](/glossary/brand-guidelines), finds the primary hex, and ships a deck. The hex is from last spring. The client updated their palette in a kickoff three months ago, someone noted it in a call recap, and nobody changed the guidelines doc. Now there's a revision round, an awkward email, and a client quietly wondering whether the agency reads its own notes. **The doc wasn't wrong when it was written. It just kept sitting there looking right while the truth moved on.** That's knowledge decay: information that was accurate on the day it was saved, slowly drifting out of date while it still presents as the source of truth. It's the retainer SOP describing a billing process you changed two quarters ago. It's the discovery brief still quoting positioning the client walked away from. It's the onboarding doc that lists a tool you migrated off. None of it announces that it's stale. People keep acting on it because there's no signal that says don't. The reason decay is so expensive is that it's invisible until someone trips on it. A doc that's wrong but obviously old gets double-checked. A doc that's subtly fourteen months behind gets trusted—**and that trust is exactly what turns a stale file into a revision round or a client losing confidence**. The agencies that get burned aren't the ones with no documentation. They're the ones with documentation nobody re-checks, where "we have it written down somewhere" quietly stopped meaning "it's still true." heykiku puts an expiry clock on every document so decay has somewhere to surface. Set a review interval (default ninety days), and as a doc approaches it the system flags it due, then overdue, raises a review banner, and a background worker notifies the people who can act—an approver hits **Mark as reviewed** to reset the clock or opens it to fix what changed. And before you've set any of that up, the [agency knowledge debt calculator](/calculator) lets you put a number on what decay is already costing you, so the case for fixing it isn't a hunch. --- # Knowledge Silos URL: https://heykiku.com/glossary/knowledge-silos When an agency has knowledge silos, the symptom isn't missing information—it's information that exists but can't be found. The designer knows which logo version is current, but the freelancer doesn't. The account manager remembers the client's pet peeves, but nobody told the new hire. The [brand guidelines](/glossary/brand-guidelines) exist, but they're in a Dropbox folder three people can access. **The knowledge is there; the path to it is broken**. Silos in an agency context aren't intentional hoarding. They're the natural consequence of how agencies grow. A senior designer builds shortcuts nobody else learns. Each new client gets a folder structured however the account lead felt that week. Tools accumulate as teams pick whatever fits their workflow. By year three, **critical information lives in twelve places** and no two people know where to look first. The traditional fix is to mandate a single tool. It never works. Teams need the tools that fit their workflow, not a forced platform that flattens everything into one shape. Within six months, shadow silos appear again—the designer still uses Figma, the writer still uses Docs, and nobody's moving to the mandated wiki. **Access is the silo, not the tool**. heykiku removes silos without removing the tools agencies already use. Upload the documents that matter—brand guidelines, SOPs, client history, past briefs—and one AI assistant knows where everything lives, with role-based access so freelancers see what they should and sensitive details stay protected. When someone asks "where are Client X's approved fonts?", the answer comes back in seconds instead of a Slack thread that takes three hours to resolve. --- # Offboarding URL: https://heykiku.com/glossary/offboarding When someone leaves, they take more than their personal belongings. They take client relationships, process shortcuts, historical context, and **answers to questions nobody thought to ask yet**. The two-week notice period is your last chance to capture what's in their head. The real cost of poor offboarding **shows up months later**. Why did we set up the Client X account that way? What was the context behind that pricing decision? How do we handle the edge case that only Sarah knew about? These questions have no answers because Sarah left and took the knowledge with her. Most agencies don't have an offboarding process at all. There's an exit interview HR runs, maybe a goodbye lunch. But nobody sits down with the departing employee and **systematically captures what they know**. Nobody asks them to record explanations of their key processes or document their client relationships. The knowledge transfer that should happen doesn't. Agencies that retain knowledge through turnover **build capture into the offboarding process**. Recorded handoff sessions. Documented client contexts. Process walkthroughs that live on after the person leaves. When knowledge capture is expected during offboarding, the next person doesn't start from zero. --- # QA Checklist URL: https://heykiku.com/glossary/qa-checklist When you're juggling twelve clients simultaneously, **brand details blur together**. Was it Client A who hates blue backgrounds, or Client B? Did Client C update their logo last month? Is Client D's campaign still using the old tagline? Without a QA checklist, these questions get answered by luck—or by client complaints. QA failures in an agency context aren't just embarrassing—**they're relationship killers**. Sending Client A's deliverable with Client B's logo isn't a typo. It's a signal that you're not paying attention. One wrong logo version and the client wonders what else you're getting wrong. Trust erodes faster than you can rebuild it. The challenge is that agency QA isn't generic web QA. It's **client-specific brand compliance at scale**. Does this match the [brand guidelines](/glossary/brand-guidelines) we have on file? Are we using the latest assets? Does the messaging align with the [tone document](/glossary/tone-of-voice)? These checks require accessible, current brand documentation—not just a generic proofreading pass. Effective agency QA checklists reference client-specific requirements, not just universal standards. They link to the brand guidelines. They flag client-specific pet peeves. They're updated when clients rebrand. When **QA is connected to your knowledge base**, checking becomes quick. When it's not, checking becomes guessing. --- # Rate Card URL: https://heykiku.com/glossary/rate-card "What do we charge for that?" It's a simple question that reveals a common agency problem. When pricing isn't documented and accessible, team members **make up prices**, underquote to win deals, or interrupt founders mid-meeting to get answers. A rate card creates **pricing consistency**. Whether a senior account manager or junior coordinator is scoping work, they reference the same prices. This prevents the awkward situation where one client pays significantly more than another for identical work. But rate cards only work if people use them. A PDF buried in a shared drive is marginally better than no rate card at all. Effective rate cards are **findable in seconds**, updated regularly, and integrated into your scoping and quoting processes. The best rate cards include **context, not just numbers**. When does the standard rate apply versus rush pricing? What's included at each price point? How do volume discounts work? This context helps your team quote accurately without needing to escalate every decision. --- # Retainer URL: https://heykiku.com/glossary/retainer Retainers are the **foundation of sustainable agency revenue**. Unlike project work, which creates feast-or-famine cycles, retainers provide predictable income month after month. They enable long-term planning, stable teams, and deeper client relationships. But retainers only work when delivery is consistent and efficient. When every month requires reinventing processes, hunting for past work, or rediscovering client preferences, margins erode. **Predictable revenue becomes unpredictable cost**. The agencies that profit from retainers are the ones with **systematic approaches to recurring work**. Documented processes. Accessible client information. Clear scope boundaries. Templates and workflows that make the hundredth month as efficient as the first. Knowledge management is the invisible infrastructure behind profitable retainers. When your team can quickly find past work, understand client preferences, and follow established processes, retainer work stays profitable. When they're constantly searching, asking questions, or rebuilding from scratch, retainers become **money losers dressed as steady income**. --- # Retrospective URL: https://heykiku.com/glossary/retrospective Every agency learns from their projects. **Some learn systematically; most learn accidentally**. The difference is whether insights get captured in ways that inform future work, or whether they vanish with the next deadline. Retrospectives—also called post-mortems or debriefs—create structured moments for reflection. What worked well? What caused problems? What would we do differently? These conversations happen naturally over coffee and in Slack threads. The retrospective **formalizes them into actionable insights**. The challenge isn't running retrospectives. Most agencies do them, at least for major projects. The challenge is making **retrospective insights findable and actionable**. A brilliant observation in a meeting that nobody documents helps nobody. An insight captured in a Google Doc that nobody can find is equally useless. Effective retrospective processes include documentation habits. Standard formats for capturing insights. Clear ownership for implementing changes. A **searchable repository** so patterns across projects become visible. When retrospective insights accumulate and stay accessible, agencies actually improve over time instead of repeating the same mistakes. --- # Revision Round URL: https://heykiku.com/glossary/revision-round Revision rounds exist to protect both **agency profitability and client satisfaction**. Without defined limits, projects drift into endless feedback loops. Clients keep requesting changes because nobody said they couldn't. Agencies over-deliver because saying no feels awkward. The solution isn't being rigid or difficult—it's **being clear upfront**. Two rounds of revisions included. Additional rounds at hourly rate. Clear deadlines for consolidated feedback. These boundaries actually improve client relationships by setting expectations and creating urgency for decisions. But revision policies only work when **everyone knows them**. When the policy is buried in a contract nobody references, it might as well not exist. When account managers can't confidently cite the policy because they don't know where to find it, [scope creeps](/glossary/scope-creep) in. **Accessible revision documentation** protects everyone. Account managers can reference it in client conversations. Project managers can plan timelines around it. Clients understand the structure from the beginning. When revision processes are clear and findable, projects stay profitable without feeling restrictive. --- # Scope Creep URL: https://heykiku.com/glossary/scope-creep Scope creep is one of the **most common profitability killers** for agencies. It rarely starts with a dramatic demand. Instead, it's a series of small requests. "Can we just add one more page?" "Could you tweak this one thing?" "I know it wasn't in the scope, but..." Each request seems reasonable in isolation. Saying no feels petty. So you say yes. And yes again. Before you know it, you've delivered far more than you quoted for. **Your margins have evaporated**. Your team is frustrated. And the client has learned that your scope is negotiable. The root cause of scope creep is often **a knowledge gap**—either yours or the client's. "I didn't know that wasn't included." "I thought revisions were unlimited." "We assumed you'd handle that." Clear documentation prevents these assumptions from becoming expensive misunderstandings. Preventing scope creep starts before the project begins. Clear [SOWs](/glossary/statement-of-work) with explicit inclusions and exclusions. Defined [revision rounds](/glossary/revision-round). [Change order](/glossary/change-order) processes that everyone understands. But the documentation only works if it's **accessible—to your team and to clients**—when questions arise. --- # Service Packages URL: https://heykiku.com/glossary/service-packages Custom proposals for every client might seem like personalized service. In practice, they create **inefficiency on both sides**. Clients struggle to compare options. Your team spends hours scoping and pricing work that's fundamentally similar to past projects. Service packages solve this by **productizing your offerings**. A "Starter SEO Package" with defined deliverables. A "Monthly Social Media Management" tier. A "Brand Identity Package" with clear components. Clients understand what they're buying. Teams know exactly what to deliver. The challenge with packages isn't creating them—it's **maintaining clarity about what's included**. When package details live in old proposals, sales decks, or people's heads, delivery becomes inconsistent. One client gets more than another for the same package. Margins vary based on who's delivering. Successful packages require accessible documentation that everyone references—sales when pitching, project managers when planning, teams when delivering. When the package definition is the **[single source of truth](/glossary/single-source-of-truth)**, clients get consistent value and agencies maintain consistent margins. --- # Single Source of Truth URL: https://heykiku.com/glossary/single-source-of-truth "Which version is current?" is the question that reveals whether an agency has a single source of truth. If the answer involves checking timestamps, asking the original creator, or guessing based on filename conventions, the answer is no. **A single source of truth means the question never needs to be asked**. Agencies fail at this because their information doesn't start in one place. Logos arrive by email. [Brand guidelines](/glossary/brand-guidelines) come as PDFs attached to contracts. Rate cards live in the founder's Google Drive. Tone of voice exists as a Slack message someone screenshot two years ago. Each item is stored somewhere; none are consolidated. When the designer needs the current primary color hex code at 4pm on a Friday, there are three versions and no way to know which one the client actually approved. Every agency has tried the shared drive approach. Within a month, someone emails a "final-final-v2" that never makes it back to the drive. The central location goes stale, people stop trusting it, and the silos return. **Consolidation isn't the hard part—staying consolidated is**. Without enforcement, the source of truth drifts into just another folder. heykiku makes the source of truth the fastest place to get an answer. When your team asks a question, the answer comes from uploaded documents—not from memory, not from last month's email, not from the version someone saved locally. **The path of least resistance becomes the authoritative path**. When getting the right answer is quicker than hunting for an old one, the single source of truth actually stays single. --- # Standard Operating Procedures URL: https://heykiku.com/glossary/standard-operating-procedures There's a moment every growing agency hits: the work is still getting done, but the founder is in every decision, every handoff, every client interaction. Not because they want to be, but because they're the only one who knows exactly how things should go. That's not a people problem. **That's a systems problem** — and Standard Operating Procedures are the fix. SOPs shift quality from **person-dependent to process-dependent**. When the best account manager on your team handles onboarding, it goes well because of who they are. When that same process is documented as a standard procedure, it goes well because of how it's designed. The difference is the difference between a business that scales and one that plateaus. The compliance dimension is underrated. When something goes wrong with a client — a missed deadline, a miscommunication, a deliverable that didn't match the brief — documented procedures tell you whether the problem was **human error or process failure**. Without SOPs, every mistake looks like someone's fault. With them, you can trace where the breakdown happened and fix it at the source. SOPs also determine what you can actually delegate. You can't hand off a task you've never written down. Every procedure you document is a task you can delegate, a bottleneck you remove, and **a step toward building a team that operates without you** in every conversation. --- # Statement of Work (SOW) URL: https://heykiku.com/glossary/statement-of-work The Statement of Work is supposed to be the definitive reference for what's included in a project. In reality, most agency SOWs are **buried in Google Drive folders** nobody can find. They're referenced during sales, filed after signing, and forgotten until a dispute arises. This creates a dangerous situation. When scope questions come up—and they always do—**nobody checks the SOW** because finding it takes too long. Instead, people rely on memory, make assumptions, or just say yes to avoid conflict. The document designed to prevent [scope creep](/glossary/scope-creep) becomes useless. A good SOW does more than list deliverables. It **explicitly states what's not included**. It defines [revision rounds](/glossary/revision-round) and change processes. It establishes acceptance criteria so both sides know when work is complete. Most importantly, it's accessible to everyone who needs to reference it. The format of your SOW matters less than its accessibility. Whether it's a formal legal document or a simple project brief, the key is that your team can **find it and use it** when questions arise. An SOW that prevents one scope dispute pays for itself many times over. --- # Team Onboarding URL: https://heykiku.com/glossary/team-onboarding The first week of a new hire **reveals everything wrong** with your agency's knowledge management. Where do I find the brand guidelines? How do we handle revisions? Who approves what? Each question interrupts someone who should be doing billable work. Multiply by every new hire, every year. Poor onboarding costs more than frustration. It costs billable hours spent answering basic questions. It costs mistakes made by people who didn't know better. It costs **the slow ramp to productivity** that stretches weeks into months. And it costs you the new hire's confidence that they joined a well-run operation. The challenge is that onboarding requires **knowledge that nobody has documented**. The veteran account manager knows exactly how Client X likes their reports formatted—but that's never been written down. The senior designer knows the unwritten rules about revision rounds—but the new designer has to learn the hard way. Onboarding surfaces all the [tribal knowledge](/glossary/tribal-knowledge) you've been meaning to capture. Agencies with fast onboarding have one thing in common: **accessible, searchable knowledge**. New hires don't need to memorize everything or find the right person to ask. They need to know where to look. When the answer to "how do we do this?" is always "check the knowledge base," onboarding becomes self-serve instead of a burden on your team. --- # Tone of Voice URL: https://heykiku.com/glossary/tone-of-voice The copywriter finishes the first draft of a B2B whitepaper and sends it over. The founder replies three hours later: "This doesn't sound like us." When pressed on what specifically, the answer is "I can't quite put my finger on it — it's just not right." The copywriter rewrites, guessing at what "us" means. The second draft comes back with the same feedback. **Two days gone, neither side can explain what changed, and both walk away frustrated**. Tone of voice is the most consequential piece of brand knowledge agencies regularly fail to capture properly. Tone docs usually exist — they're written during onboarding, buried in a deck, and forgotten within three months. The issue is that tone is a high-resolution thing. "Professional but warm" covers a dozen different voices. "We're not a corporate brand" excludes everything and defines nothing. Without **specific examples of what the client loved and what they rejected**, the writer is decoding mood from vibes — and mood is unreliable at scale. The other failure mode is that tone guidance lives with the person who originally wrote it. The senior copywriter knows the client wants contractions but no exclamation marks, hates the word "solutions," and refuses to say "at the end of the day." None of that is documented anywhere. When that copywriter leaves or moves to another account, **the new writer starts the discovery process from scratch** — and clients feel the inconsistency long before they can explain it. heykiku turns tone into captured knowledge that survives staff changes. Upload the tone doc, examples of past approved work, and explicit client feedback (including rejected drafts and the reasons they were rejected). Any writer on the team can then ask specific questions: "Does Client X allow contractions?" "Have they approved humor in body copy before?" "What did they say about the last LinkedIn post that used 'we believe'?" The answers come from actual evidence, not from guessing what the client meant. **Tone stops being a guessing game and becomes a reference anyone can check in the thirty seconds before they hit send.** --- # Tribal Knowledge URL: https://heykiku.com/glossary/tribal-knowledge "Ask Sarah, she knows how that client likes their reports." "Check with Mike, he remembers why we set it up that way." "Oh, that's just how we've always done it." These phrases signal tribal knowledge—**critical information that lives in people's heads** instead of documented systems. Tribal knowledge isn't inherently bad. It's a natural result of people learning and adapting. The problem is when it becomes the only way information is stored. When Sarah goes on vacation, who answers the question? When Mike leaves for another job, **that knowledge leaves with him**. The **real cost of tribal knowledge is invisible** until it's not. Projects stall because the one person who knows something is unavailable. Quality suffers because new team members don't know the nuances. Clients get inconsistent experiences depending on who's handling their account. Capturing tribal knowledge doesn't require a documentation project. It requires **making capture effortless**. Voice notes instead of writing. AI that surfaces answers when people ask questions. Role-based access so the right knowledge reaches the right people. When capturing knowledge is as easy as explaining something once, tribal knowledge becomes documented knowledge—without changing how your team works. --- # Utilization Rate URL: https://heykiku.com/glossary/utilization-rate Utilization rate seems simple: billable hours divided by total available hours, times 100. A designer who bills 30 hours out of 40 available has 75% utilization. But beneath this simple formula lies one of the **most important—and most misunderstood**—agency metrics. The first challenge is **defining what counts as billable**. Is internal creative development billable? What about client calls that run long? How do you handle time spent fixing problems caused by unclear briefs? Without documented definitions, utilization data becomes unreliable. The second challenge is tracking accurately. When timesheets are confusing, submitted late, or require guessing about past work, **the data becomes garbage**. Clean utilization tracking requires clear categories, easy logging, and processes that make accurate tracking the path of least resistance. Understanding your utilization requires context. Different roles have different targets. Account managers might aim for 60% because of relationship management overhead. Designers might target 80%. Knowing what's healthy requires **documented benchmarks and historical data** you can actually find and analyze. --- # White Label URL: https://heykiku.com/glossary/white-label White label partnerships let agencies offer services beyond their core expertise. A design agency partners with a development shop. A content agency outsources video production. A small agency accesses enterprise capabilities through a larger partner. **Everyone wins—in theory**. In practice, white label relationships fail when **knowledge transfer breaks down**. The front-facing agency can't clearly communicate client requirements. The production partner doesn't understand brand standards. Work goes through multiple revision rounds because expectations weren't documented upfront. Successful white label partnerships require **exceptional documentation**. Brand guidelines that production partners can actually use. Brief templates that capture everything needed. Quality standards that everyone references. Communication protocols that prevent things from falling through cracks. The agencies that profit from white label relationships—on either side—are the ones that treat **documentation as infrastructure**. Every failed [handoff](/glossary/handoff) costs money. Every miscommunication requires rework. Clear, accessible information transforms white label from a liability into a scalable advantage. --- # AI Chat Assistant URL: https://heykiku.com/help/ai-chat The chat is where your team gets answers. heykiku's [AI chat assistant](/features/ai-chat) takes a question in plain language and answers it from your documents, with citations. Ask a question, get an answer. ## How It Works heykiku has one AI agent trained on your uploaded documents. When someone asks a question: 1. The AI searches your knowledge base 2. It finds relevant content the user can access 3. It generates an answer with source citations 4. The user can verify by clicking through to the original document ## Access Control in Chat The AI only searches documents the user can access. A freelancer asking about pricing won't get answers from Sensitive-tier content—even if that content would answer their question. This happens automatically. No configuration needed. ## What Makes heykiku Different **Only your content:** Answers come from your documents, not the general internet. No hallucinations from random web content. **Source citations:** Answers show where the information came from. Citation chips appear inline — click one to open that document directly in the Knowledge panel without leaving chat. If a document was deleted after the answer was generated, clicking its chip won't open anything — the chip turns into plain text, and hovering it shows "Document no longer available". Deleted documents are also left out of the Sources list under the answer. **Sidebar locked during answers:** While an answer is streaming, the conversation list in the sidebar is locked — you can't switch conversations or start a new one until the answer finishes. This prevents the partial answer from getting cut off. **Role-aware:** Different team members get different answers based on their access level. ## Conversation Context Within a session, the AI remembers what you've discussed. You can ask follow-up questions: - "What's our revision policy?" → Answer - "What about rush projects?" → Knows you're still asking about revisions Start a new chat when switching topics. ## Find a past conversation Use the search field at the top of the conversation list to filter by title. Conversations are titled automatically based on your first message, so searching for the topic usually finds the right one. Press Cmd+K (or / on the chat page) to jump to the search field. Search works while heykiku is mid-answer. If you click a result, heykiku waits for the current answer to finish before switching. ## When There's No Answer If heykiku can't find relevant content, it tells you honestly rather than making something up. This is a signal to: - Upload a document covering this topic - Record a voice memo explaining it --- # API best practices URL: https://heykiku.com/help/api-best-practices Following these conventions keeps your integrations stable, your audit trail clean, and your blast radius small when a key leaks. ## Scope of least privilege Default to `read` scope. Only mint a `read + write` key if your integration actually uploads documents, creates folders, or approves drafts. A read-only integration that gets compromised can't damage your knowledge base. A write-scope key with a bad rotation policy is the one that wipes folders. ## Name keys descriptively The key name is the only label you'll have when auditing usage in the dashboard. `"CI Document Sync — production"` beats `"key-1"` six months later. ``` ✓ "Notion → heykiku sync (production)" ✓ "Google Drive ingest (staging)" ✗ "test" ✗ "my key" ``` ## One key per integration Don't share a single key across multiple integrations. If you need to revoke one to roll credentials, the others shouldn't break. This also keeps your audit logs readable — the `apiKeyNameSnapshot` field on conversations records *which* key or OAuth client started the chat, and that signal disappears when one key serves three different systems. ## Always scope keys to a CIDR for production A key with no CIDR allowlist works from any IP on the internet. For server-to-server integrations where you know the origin, set `allowedCidrs` to the runner's public IP range. For a single VPS, a /32 is fine. Be careful with `0.0.0.0/0` — it's equivalent to no allowlist and the API rejects it at issuance to prevent accidental holes. CI runners with rotating IPs are the tricky case. Most managed CI providers publish an egress IP list — check your CI's docs and paste those ranges into the key's allowlist. ## Rotate on a schedule, not on incident If you wait for an incident to rotate keys, you'll roll under pressure and make mistakes. Pick a cadence — quarterly for production, monthly for high-risk integrations — and rotate. The simplest rotation flow: 1. Create a new key with the same scope and CIDR as the old one 2. Deploy the new key to your integration 3. Verify it works for a day 4. Revoke the old key `expiresAt` makes this enforced: a key that auto-expires forces the rotation to happen on a schedule whether you remember or not. ## Never commit keys Use environment variables, secret managers, or your CI's encrypted-vars feature. `.env` files belong in `.gitignore` — heykiku keys in a public repo get auto-revoked, but that's the safety net, not the plan. If you do leak a key: 1. Revoke it immediately (`DELETE /api/api-keys/{id}`) 2. Audit the conversations and documents touched while the leaked key was live 3. Issue a new key with tighter CIDR scoping ## Monitor `X-RateLimit-Remaining` If your integration starts approaching the bucket ceiling, you'll see it in `X-RateLimit-Remaining` before it manifests as 429s. Catching this early lets you batch or back off without user-visible failures. See [rate limits and error codes](/help/api-rate-limits) for the full table. --- # API versioning policy URL: https://heykiku.com/help/api-versioning ## How URL versioning works All endpoints today live under `/api/*` — this is the permanent v1 surface. v1 is not a "latest" pointer; it's a frozen contract. When we ship breaking changes, v2 lives at `/api/v2/*`. v1 stays available for at least 12 months from the v2 announcement. v3 ships at `/api/v3/*` — v1 never auto-upgrades. Pin your clients to the version you tested against. ## What's a backwards-compatible change Adding any of the following doesn't require a new API version: - A new endpoint - New optional fields in existing request schemas - New fields in response bodies - New error codes (the set of `code` strings is open-ended; clients should handle unknown codes gracefully) - New scope values may be added. The semantics of existing scope names are frozen for the life of the API version — a scope's allowed actions never get tighter. Note that effective access also depends on your membership: a scope that passes today may fail later if your workspace role is changed by an admin. ## What's a breaking change We bump the version when we: - Remove or rename an existing field - Change a field's type or semantics - Tighten validation (a previously-accepted input becomes a 400) - Remove a scope or change what a scope grants - Change the meaning of an existing error `code` ## What you can and can't depend on **Error `code` strings are stable.** If you're switching on a code today, that code keeps the same meaning for the life of the API version. **Error `message` strings are not stable.** Display the message to humans; don't pattern-match it in code. **Cursor pagination tokens are opaque.** Treat them as strings; don't parse them. We may change their internal structure at any time. **HTTP status codes are part of the contract.** A 401 stays a 401 for the same error class. ## Deprecation policy When we deprecate a scope, key format, or header semantic, we announce it at least 12 months before removal. During the deprecation window, every response that uses the deprecated artifact includes `Deprecation: ` (RFC 9745) and `Sunset: ` (RFC 8594) headers — the deprecation date and the removal date respectively. ## Errors Our error envelope is `{ error: { code, message, doc_url? } }`. The `code` is a stable identifier; the `message` is human copy. `doc_url`, when present, points back to this page. We'll move per-code documentation into dedicated pages as the platform matures. --- # Approve Documents URL: https://heykiku.com/help/approve-document Documents stay in "Pending Review" until you approve them. Approval makes them searchable. ## Who Can Approve You need the **Approve** permission. Owners and Admins have it by default. Other members need it [granted explicitly](/help/manage-team-permissions) in the Team settings. If you don't have the Approve permission, the Approve button won't appear. ## Why Approval Exists Not everything you upload should go live immediately: - OCR might have errors - Content might need cleanup - You might want to remove sensitive sections Approval gives you a quality gate. ## How to Approve 1. Go to **Knowledge** 2. Find documents with status "Pending Review" 3. Click to open and review the extraction 4. If the content looks good, click **Approve & index** The document is now searchable. Your team can find it via chat. When a document finishes processing, everyone with the Approve permission gets a [notification](/help/notifications) so you know when content is ready for review. ## What Happens on Approval 1. The document is indexed in your knowledge base 2. Status changes to "Complete" 3. The content becomes searchable in chat 4. Your team can get answers from this document ## Can't Approve? If the **Approve & index** button doesn't appear: - Check that you have the Approve permission (ask an Owner or Admin) - Make sure the document is in "Pending Review" status (not still processing) ## Need to Make Changes After Approval? You can [edit an approved document](/help/edit-approved-document) — this temporarily removes it from search while you make changes, then you re-approve it. --- # Ask Your First Question URL: https://heykiku.com/help/ask-first-question Once you have approved documents, you can start asking questions. Here's how. ## How to Ask 1. Go to **Chat** 2. Type your question naturally: "What's our revision policy?" or "How do we handle rush requests?" 3. Press Enter heykiku searches your documents and gives you an answer with sources. ## What Makes a Good Question **Good questions:** - "What's included in our standard website package?" - "How do we handle scope creep?" - "What are the brand colors for Client X?" **Less effective:** - Single words like "pricing" (too vague) - Questions about content you haven't uploaded yet ## Understanding Answers Each answer shows: - The response based on your documents - **Sources** — which documents the answer came from - Links to view the original content If heykiku can't find relevant content, it will tell you rather than making something up. ## No Answer Found? This means the knowledge isn't in your uploaded documents yet. Consider: - Uploading a document that covers this topic - [Recording a voice memo](/help/voice-capture) to explain it --- # Authentication and key management URL: https://heykiku.com/help/api-authentication All REST API requests authenticate via a Bearer token in the standard `Authorization` header. If you haven't minted a key yet, start with [getting started with the REST API](/help/api-getting-started). ## Header format ``` Authorization: Bearer kiku_live_<48-byte-base62> ``` The `kiku_live_` prefix identifies a production key. We only ever issue live keys today — there's no separate test environment, no `kiku_test_` keys for now. ## The key prefix is safe to log Every API key has a short, non-secret `keyPrefix` (the first 18 characters). Logging the prefix is safe: it identifies *which* key made a request without exposing the secret. The prefix appears in API key listings and in our internal audit logs. ``` "kiku_live_abc123..." ← log this "kiku_live_abc123XYZ..." ← never log this ``` ## CIDR allowlist When you create or update a key, you can restrict it to a list of IPv4 CIDR blocks. Any request from outside the allowed ranges is rejected with a 403. Use this for CI runners, server-to-server integrations, and any workload with a known origin. Set it to your office IP if you're testing locally; remove it before going to production. Today we support IPv4 only — IPv6 CIDRs are rejected at issuance time with a clear error message. ## Expiry Set `expiresAt` (ISO 8601) on a key to make it auto-expire. The earliest allowed expiry is the start of tomorrow (UTC) — an expiry of today or earlier is rejected at issuance. After the expiry instant the key behaves like a revoked key: requests fail with a 401 `API_KEY_INVALID`. The dashboard flags keys expiring within 14 days so you can rotate before they die. Plan a rotation ahead of the expiry date — see [API best practices](/help/api-best-practices) for the recommended flow. ## Updating a key `PATCH /api/api-keys/{id}` lets you change the **name**, **CIDR allowlist**, and **expiresAt** without rotating the secret. The scope is immutable post-creation — to change scope, revoke and re-create. ```bash curl -X PATCH \ -H "Authorization: Bearer kiku_live_..." \ -H "Content-Type: application/json" \ -d '{"allowedCidrs":["203.0.113.0/24"]}' \ https://heykiku.com/api/api-keys/ ``` ## Revoking a key `DELETE /api/api-keys/{id}` revokes the key immediately. Revocation is permanent — there's no un-revoke. Returns 204 No Content on success. If a key is compromised, revoke first and ask questions after. ## Break-glass revoke (owner) If a team member leaves, the workspace owner can revoke **all** of that member's keys at once from the team page. Removing the member entirely (`Remove` action) also cascades a revoke automatically — every active key owned by that account stops working immediately. --- # Billing Essentials URL: https://heykiku.com/help/billing-essentials Everything billing-related lives at **Settings** → **Billing**. ## Who Can Manage Billing By default, only the workspace **Owner** can change plans, cancel, or buy add-ons. Admins can view billing information but cannot take action unless the Owner grants them billing access — see [manage team permissions](/help/manage-team-permissions) for how to do that. If you see billing information but no action buttons, ask your Owner to grant you billing access. ## Plans heykiku has two paid plans: | Plan | Price | Members | Monthly messages | |------|-------|---------|------------------| | Seed | $29/mo | Up to 5 | ~20 per person/day | | Bloom | $79/mo | Up to 15 | ~20 per person/day | Bloom unlocks the freelancer role and, with it, the general access tier that freelancers can read. The internal, sensitive, and owner-only tiers are available on every plan. **To switch plans:** 1. Go to **Settings** → **Billing** 2. Click the plan card you want to move to 3. Confirm the change Upgrades take effect immediately. Downgrades take effect immediately too, but may pause team members who exceed the new plan's seat limit — you'll see a preview before confirming. ## Extra Messages If your team hits the monthly message limit, you can buy 1,000 extra messages for $9 without changing your plan. These credits don't expire — they carry over until used. When you're near the limit, a **Buy 1,000 extra** button appears in the sidebar usage widget. You can also trigger the same purchase from the chat when you hit the cap. The dialog is titled "Buy extra messages" and walks you through a Polar checkout. ## Update Your Payment Method 1. Go to **Settings** → **Billing** 2. Click **Manage billing** — this opens the Polar billing portal in a new tab 3. Update your card details in the portal ## Invoice Copies by Email If you want billing receipts sent to a specific email address (your accountant, for example): 1. Go to **Settings** → **Billing** 2. Find the **Invoice copies** section 3. Enter the email address and save ## Starting a Cancellation See [cancelling and reactivating your subscription](/help/cancel-and-reactivate-subscription) for the full walkthrough. The cancel button is in **Settings** → **Billing** and only appears to users with billing access. --- # Bulk Move and Delete Documents URL: https://heykiku.com/help/bulk-actions When you need to reorganize or clean up your knowledge base, bulk actions save time. ## Requirements - **Upload** permission to see checkboxes and use bulk delete - **Organize** permission to use bulk move ## Selecting Documents 1. Go to **Knowledge** 2. Hover over any document row to reveal a checkbox 3. Click the checkbox to select it 4. Select as many documents as you need In the grouped folder view, clicking a folder's checkbox selects all documents in that folder. Once any document is selected, a **floating action bar** appears at the bottom of the page showing "N selected" and your available actions. ## Bulk Move Click the **Move to folder** dropdown in the action bar, then select a destination folder (or "Unfiled" to remove from a folder). **Restrictions:** - All selected documents must share the same access level (folders are tied to one access level) - You need the **Organize** permission - The dropdown only shows folders that match the common access level If you select documents from mixed access levels, the Move button is disabled with a tooltip explaining why. ## Bulk Delete Click the red **Delete** button in the action bar. A confirmation dialog shows how many documents you're about to delete. Click confirm to proceed. ## After Bulk Actions **Move:** Toast shows "Moved N documents to [folder name]". Documents appear in their new folder immediately. **Delete:** Toast shows "Deleted N documents". If some documents couldn't be deleted (e.g., currently processing), you'll see a partial success message. Selection is cleared after any bulk action completes. ## Tips - Use bulk move after creating a new folder to organize existing content - Filter by access level first to make selection easier - Checkboxes disappear when you apply a search filter (bulk actions work on the default view) --- # Cancel and Reactivate Your Subscription URL: https://heykiku.com/help/cancel-and-reactivate-subscription ## Who Can Cancel Only users with billing access can cancel. That means the workspace Owner, or Admins who have been granted the Billing permission by the Owner. See [manage team permissions](/help/manage-team-permissions) for how billing access works. ## How to Start a Cancellation 1. Go to **Settings** → **Billing** 2. Click **Cancel subscription** 3. You'll be asked why you're leaving — pick the option that fits best and click **Continue** ## Save Options Before You Cancel After you pick a reason, heykiku may show a save option — an alternative plan that fits a smaller team or lighter use. If it appears, you'll see exactly what it includes (and how it would affect your members) before you confirm anything. To skip the offer and cancel outright, click the cancel link at the bottom of that screen. ## What Happens After Cancellation - You keep full access until the end of your current billing period - A banner on the Billing page confirms the cancellation date - After the period ends, the workspace locks and data is retained but inaccessible ## Reactivate Before the Period Ends If you change your mind before the billing period ends: 1. Go to **Settings** → **Billing** 2. Click **Resume subscription** This cancels the scheduled cancellation and your subscription continues uninterrupted. ## Reactivate After the Period Ends Once the period ends and the workspace locks, you need to start a new subscription: 1. Go to **Settings** → **Billing** — this page stays accessible even when locked 2. Choose a plan and complete checkout 3. Your workspace unlocks immediately after the payment processes Your data is retained after the period ends — nothing is deleted when a workspace locks. --- # Common API workflows URL: https://heykiku.com/help/api-common-workflows These workflows cover the high-frequency endpoints. All examples use a Bearer token (see [API authentication](/help/api-authentication)). For the complete list of endpoints with request/response shapes, see the [API reference](/api-reference). ## List documents `GET /api/documents` returns documents the key's owner can see, filtered by visibility (general, internal, sensitive). Supports cursor pagination. ```bash curl -H "Authorization: Bearer kiku_live_..." \ "https://heykiku.com/api/documents?search=onboarding&limit=20" ``` Query parameters: - `search` — case-insensitive substring match on the document filename (max 100 characters) - `tagId` — filter by access tag (the visibility tier) - `folderId` — filter by folder - `status` — one of `pending`, `processing`, `pending_review`, `approved`, `complete`, or `failed` - `staleness` — `due` (review date reached) or `overdue` (review date passed). Approver-only: a key whose owner can't approve gets a 403. Takes precedence over `status` when both are sent - `cursor` + `limit` — keyset pagination, 1–100 per page (default 20) The response nests `hasMore` and `cursor` under a `pagination` object: ```json { "documents": [ /* ... */ ], "pagination": { "hasMore": false, "cursor": null } } ``` ## Upload a document `POST /api/documents` (multipart/form-data). Requires `write` scope. ```bash curl -X POST \ -H "Authorization: Bearer kiku_live_..." \ -F "file=@./brief.pdf" \ -F "accessTagId=" \ -F "folderId=" \ https://heykiku.com/api/documents ``` Call `GET /api/access-tags` first to find valid `accessTagId` values for your workspace. Each tag maps to a visibility tier — uploading to the wrong tier is the most common cause of "user can't find the document later." ## List folders and tags ```bash curl -H "Authorization: Bearer kiku_live_..." https://heykiku.com/api/folders curl -H "Authorization: Bearer kiku_live_..." https://heykiku.com/api/access-tags ``` Folders are a workspace-level organizational layer. Access tags are the visibility tier (`general`, `internal`, `sensitive`). ## Create a folder `POST /api/folders` requires `write` scope and a valid `accessTagId`: ```bash curl -X POST \ -H "Authorization: Bearer kiku_live_..." \ -H "Content-Type: application/json" \ -d '{"name":"Q3 briefs","accessTagId":""}' \ https://heykiku.com/api/folders ``` ## Read past conversations `GET /api/conversations` lists past chats; `GET /api/conversations/{id}` returns one with its messages array. ```bash curl -H "Authorization: Bearer kiku_live_..." https://heykiku.com/api/conversations ``` The `source` field on each conversation is `web` (started from the dashboard) or `mcp` (started by an MCP client — either with an API key or via OAuth). A third value `api` is reserved for a future REST send endpoint; no conversations carry this value today. `apiKeyNameSnapshot` records which key or OAuth client opened the conversation — useful when auditing which integration generated which traffic. ## What's not in the REST API **Sending a chat message is not a REST endpoint.** Conversation reads are REST; sends use a streaming web protocol that doesn't suit SDK codegen. For now, the REST API is read-only for conversations. Send-via-API capability is being rebuilt and will return through a separate channel. **Workspace administration is not in the REST API.** Team management, billing, and workspace settings are dashboard-only — there's no Bearer surface for these. --- # Configure Workspace Settings URL: https://heykiku.com/help/workspace-settings Customize how your workspace looks and displays dates and times. ## Who Can Change Settings Only **Owners** and **Admins** can modify workspace settings. The Settings page redirects others to Chat. ## How to Access Click **Settings** in the sidebar, then select the **General** tab (it's the default). ## Workspace icon Your icon appears in the sidebar next to your workspace name. **Upload an icon:** 1. Click **Upload icon** (or **Replace** if one exists) 2. Select a PNG or JPEG image (max 2MB) 3. Click **Upload** The icon updates immediately in the sidebar. **Remove an icon:** Click the red **Remove** button. Your workspace reverts to the default building icon. ## Timezone Select your workspace's timezone from the dropdown. This affects how dates and times are displayed throughout the dashboard. The dropdown groups timezones by region (Americas, Europe, Asia, etc.). Default: UTC. ## Date Format Choose how dates appear: | Option | Example | |--------|---------| | MM/DD/YYYY | 02/26/2026 | | DD/MM/YYYY | 26/02/2026 | | YYYY-MM-DD | 2026-02-26 | ## Time Format Toggle between: - **12-hour** — 1:30 PM - **24-hour** — 13:30 ## Saving Click **Save Changes** at the bottom. The button is only enabled when you've made changes. Settings take effect immediately after saving. --- # Connect your MCP client to heykiku URL: https://heykiku.com/help/mcp-connect heykiku's MCP server uses Streamable HTTP and OAuth to [connect your AI client to your knowledge base](/features/connect). The three clients heykiku tests against are Claude Code, Cursor, and Claude Desktop. If you haven't yet, read [how the MCP server works](/help/mcp-getting-started) before wiring up a client. MCP access is included with the Bloom plan and uses read-only scope. Your workspace MCP URL is shown on the Connected apps page. ## Before you start - Your workspace must be on the Bloom plan. - Go to Account → Connected apps to find your workspace MCP URL. - The URL is workspace-scoped. A key or OAuth token from workspace A does not work in workspace B. ## Set up Claude Code 1. Go to Account → Connected apps and copy your workspace MCP URL. 2. In your terminal, run: ``` claude mcp add --transport http heykiku ``` 3. Open Claude Code and type `/mcp` to complete OAuth authentication. A browser window will open asking you to approve `read` access for the workspace. 4. Once approved, Claude Code lists heykiku in its MCP tools. ## Set up Cursor 1. Go to Account → Connected apps. 2. Click the **Add to Cursor** deep link to open the Cursor MCP installer, which pre-fills the server URL and starts the OAuth flow automatically. 3. Alternatively, add the server manually in Cursor's MCP settings using the JSON config shown on the Connected apps page: ```json { "type": "http", "url": "" } ``` 4. Authenticate with OAuth when Cursor prompts for the heykiku consent flow. ## Set up Claude Desktop 1. Go to Account → Connected apps and copy your workspace MCP URL. 2. Open Claude Desktop settings and add a new MCP server with that URL. 3. Complete the OAuth flow when Claude Desktop opens the heykiku consent page. ## Try a first prompt Ask a question that belongs in your agency knowledge base: - "Ask kiku what our onboarding checklist says about kickoff calls." - "Search heykiku for the latest Acme brand guidelines." - "List the folders I can access." Document tools are read-only. Your client only receives results your heykiku role can see. It cannot upload, edit, approve, or delete knowledge through MCP. `flag_kiku` records review metadata for Questions to answer. Use the heykiku web app for uploads and workspace changes. ## Revoke access To disconnect an OAuth client, go to Account → Connected apps and remove the connection. For REST API keys (not MCP), go to Account → API keys. Static bearer tokens are for the REST API only — not MCP. --- # Create and Manage Folders URL: https://heykiku.com/help/create-folder Folders help you organize documents logically. Here's how to create and use them. ## Who Can Manage Folders You need the **Organize** permission to create, edit, or delete folders and to move documents. Owners, Admins, and Employees have this by default. Freelancers don't. Permissions can be [adjusted per member](/help/manage-team-permissions). If you don't have the Organize permission, the Create button won't appear. ## Create a Folder 1. Go to **Knowledge** 2. Click **Create** 3. Select the **access level** for this folder (required) 4. Enter a folder name (up to 50 characters) 5. Optionally add a **description** (up to 200 characters) 6. Optionally pick a **color** (Red, Orange, Amber, Green, Blue, Purple, or Gray) 7. Click **Create folder** ## Folder Rules - All documents in a folder share the same access tier - Folder names must be unique within each access tier - You can have the same folder name in different tiers (e.g., "Templates" in both General and Internal) ## Move Documents to Folders 1. Select a document 2. Click **Move to Folder** 3. Choose the destination folder 4. Confirm The document will inherit the folder's access tier. ## Rename or Delete Folders Each folder has a three-dot menu (**⋯**) in its header row. **Rename:** 1. Click **⋯** on the folder row 2. Click **Edit folder** 3. Change the name, description, or color 4. Click **Save Changes** **Delete:** 1. Click **⋯** on the folder row 2. Click **Delete folder** 3. Confirm — documents inside are moved to Unfiled (not deleted) ## Tips - Use client names for client-specific content - Create "Templates" folders for reusable assets - Use colors to visually group related folders --- # Document Upload & Management URL: https://heykiku.com/help/document-management Your knowledge base grows as you add documents. heykiku turns each upload into searchable [knowledge management](/features/knowledge-management) your whole team can query. Here's how document management works. ## Supported Formats | Format | Notes | |--------|-------| | PDF | Scanned or native text | | DOCX | Word documents | | XLSX | Spreadsheets (converted to searchable tables) | | TXT, MD | Plain text and markdown | | Images | PNG, JPEG, GIF, WebP (OCR extracts text) | Maximum file size: 10MB per document. ## Upload Workflow 1. **Upload** — Drag files or click to select 2. **Extraction** — heykiku pulls text from your document 3. **Review** — Check the extracted content, edit if needed 4. **Approve** — Make it searchable in your knowledge base Documents stay in "Pending Review" until you approve them. This prevents garbage from polluting your knowledge base. ## Organizing with Folders Create folders to group related content: - By client: "Client X Brand Assets" - By topic: "HR Policies" - By project type: "Website Projects" Folders inherit the access tier you choose. All documents in a folder share the same visibility. ## Editing Extractions OCR isn't perfect. Before approving: 1. Open the document 2. Click the **Extraction** tab 3. Edit text directly in the editor 4. Click **Approve & index** when ready This ensures your knowledge base contains accurate, clean content. ## Deleting Documents 1. Select the document 2. Click **Delete** 3. Confirm Deleted documents are removed from search immediately. --- # Document Won't Upload URL: https://heykiku.com/help/document-not-uploading If your document won't upload, here's how to diagnose and fix it. ## Check the Basics **File size:** Maximum is 10MB. Compress large PDFs or split them. **File format:** Supported formats are PDF, DOCX, XLSX, TXT, MD, PNG, JPEG, GIF, WebP. **File name:** Avoid special characters. Rename to something simple like `brand-guidelines.pdf`. ## Common Issues ### "File type not supported" You're trying to upload an unsupported format. Convert to PDF or a supported format. ### "File too large" Reduce file size: - For PDFs: Use a PDF compressor - For images: Reduce resolution or use JPEG instead of PNG - For large documents: Split into multiple smaller files ### Upload starts but never finishes - Check your internet connection - Try a different browser - Clear browser cache and try again ### "Permission denied" You don't have write access to the selected access tier. Ask an Admin or Owner to upload it, or choose a tier you can access. ## Still Stuck? If none of these help: 1. Note the exact error message 2. Note the file type and size 3. Contact support with these details --- # Edit an Approved Document URL: https://heykiku.com/help/edit-approved-document Sometimes you need to fix a typo or update content in a document that's already live. Here's how to edit an approved document. ## Requirements - The document must be **approved** (status: Complete) - You need the **Approve** permission ## How It Works Approved documents are indexed in the AI's knowledge base, so editing requires a two-step process: 1. **Unindex** — Temporarily remove the document from search 2. **Edit and re-approve** — Make your changes, then approve again ## Steps 1. Go to **Knowledge** and click the document to open it 2. On the **Extraction** tab, click **Edit extraction** 3. A confirmation dialog warns: "This document will be temporarily unavailable in chat while you edit. You'll need to approve it again before it's re-indexed." 4. Click **Edit extraction** to confirm 5. The document is unindexed and its status changes to **Pending Review** 6. The editor becomes active — make your changes 7. Click **Approve & index** when done ## What "Unindex" Means While you're editing, the document is removed from the AI's searchable knowledge base. Your team won't get answers from this document until you re-approve it. Keep edits quick to minimize the gap. ## Editing vs. Replacing | Action | When to Use | |--------|-------------| | **Edit extraction** | Fix text, update wording, remove sections | | **[Replace the document](/help/replace-file)** | Swap in a newer version of the original file | Editing changes the text content directly. Replacing re-processes the file from scratch. --- # Edit Extracted Text URL: https://heykiku.com/help/edit-extraction After uploading a document, heykiku extracts the text. You can edit this before making it searchable — it's one step in the broader [document upload and management](/help/document-management) workflow. ## Who Can Edit You need the **Approve** permission. Owners and Admins have it by default. Others need it [granted explicitly](/help/manage-team-permissions). ## When to Edit Edit extractions when: - OCR misread words (especially in scanned documents) - Formatting is messy (tables didn't parse correctly) - You want to remove irrelevant sections - You want to add context that wasn't in the original ## Editing a Pending Document For documents in "Pending Review" status, the editor is immediately available: 1. Go to **Knowledge** 2. Find the document (status: "Pending Review") 3. Click to open it 4. The **Extraction** tab shows the WYSIWYG editor 5. Edit directly in the editor 6. Click **Save draft** to preserve your changes ## Editing an Approved Document Already-approved documents require an extra step because they're live in your knowledge base: 1. Open the approved document (status: "Complete") 2. On the **Extraction** tab, click **Edit extraction** 3. Confirm the dialog — the document will be temporarily unavailable in chat 4. The document is unindexed and returns to "Pending Review" 5. Make your edits in the now-active editor 6. Click **Approve & index** to re-index it See [editing an approved document](/help/edit-approved-document) for details. ## Editor Features The editor supports: - **Headings** — H1, H2, H3 - **Formatting** — Bold, italic, underline, strikethrough, code - **Lists** — Bulleted and numbered - **Block quotes** — For callouts - **Tables** — With headers - **Code blocks** — For technical content A formatting toolbar appears at the top of the editor when it's active. ## Character Limit Extractions can be up to 500,000 characters. The editor shows a live character count. If you're near the limit: - Remove unnecessary content - Split into multiple documents ## After Editing Once you're happy with the content: 1. Click **Approve & index** 2. The document becomes searchable 3. Your team can now find this content via chat ## Tips - Fix OCR errors that change meaning (e.g., "can" vs "can't") - Remove boilerplate (footers, page numbers, headers) - Add context if the original assumed prior knowledge --- # Filter and View Your Knowledge Base URL: https://heykiku.com/help/knowledge-filters-and-views The Knowledge page has a filter bar above the document list. As your [knowledge base](/features/knowledge-management) grows, filters and view modes are how you narrow down to exactly what you're looking at. ## Available Filters **Search** — Type to search document titles. Results update as you type (with a short debounce to avoid firing on every keystroke). **Access level** — Filter to one tier: General, Internal, Sensitive, or Owner-only. What you see in this dropdown depends on your role — freelancers only see General; employees see General and Internal. **Folder** — Filter to documents in a specific folder. When you pick an access level first, the folder dropdown automatically narrows to folders in that tier. **Status** — Filter by processing status: Pending, Processing, Pending Review, Complete, or Failed. Users without the Approve permission see a shorter list — the Pending Review and Failed options are hidden because those statuses require approver action. **Review** — Filter to documents that are due for review or overdue. This filter is only visible to users with the Approve permission, because reviewing documents is an approver workflow. Selecting a staleness filter clears the status filter, and vice versa — they're mutually exclusive. Click **Clear** (appears when any filter is active) to reset everything at once. ## Grouped vs Flat View The document list switches between two layouts automatically: **Grouped view** — When no filters are active and your workspace has folders, documents are grouped into folder cards. Each folder card shows the folder name and its documents. "Unfiled" appears at the bottom for documents not assigned to any folder. **Flat view** — When any filter is active, or when there are no folders, documents appear as a single flat list ordered by most recently uploaded. There is no manual toggle between these views — the layout changes based on whether filters are applied. ## What Freelancers See Freelancers see only documents in the General tier. The access level dropdown shows only "General." The status dropdown omits Pending Review and Failed. The Review filter doesn't appear at all. Folders that contain only Internal, Sensitive, or Owner-only documents are invisible. --- # Four-Tier Access Control URL: https://heykiku.com/help/access-control Not everyone should see everything. heykiku's [four-tier access control](/features/access-control) protects sensitive information while keeping useful content accessible to the people who need it. ## The Four Tiers | Tier | Who Can Access | Example Content | |------|----------------|-----------------| | **General** | Everyone, including freelancers | Processes, brand guidelines, playbooks | | **Internal** | Employees only | Internal rates, team structure | | **Sensitive** | Admins and owners | Client pricing, profit margins | | **Owner-only** | Just you | Salary bands, strategic plans | ## How It Works When you upload a document, you assign it to a tier. When someone asks a question, heykiku only searches documents they're allowed to see. A freelancer asking "What's the client rate?" won't see your internal pricing document. They'll only get answers from General-tier content. ## Roles and Access Each team role maps to specific tiers: | Role | Can See | |------|---------| | Owner | All four tiers | | Admin | General, Internal, Sensitive | | Employee | General, Internal | | Freelancer | General only | ## Why This Matters Agencies work with mixed teams—employees, freelancers, contractors. Most tools force you to choose between sharing everything or nothing. heykiku lets you share processes and playbooks with freelancers while keeping margins and client details private. No complex permission matrices. Just four clear levels. --- # Get started with the MCP server URL: https://heykiku.com/help/mcp-getting-started The heykiku MCP server lets you [connect Claude and Cursor to your knowledge base](/features/connect), so Claude Code, Cursor, or Claude Desktop can query your agency knowledge as a tool — the same role-aware knowledge your team uses in the dashboard, available inside your AI client. Document tools are read-only, and queries respect your role's access tiers. `flag_kiku` records review metadata — it does not write documents. (MCP — Model Context Protocol — is the open standard these clients use to call external services.) MCP access is included with the Bloom plan and draws from your plan's message budget when you use `ask_kiku`. MCP can answer questions, search knowledge, list folders, read document metadata or extracted text, and flag an answer for review. It cannot upload files, edit documents, change folders, approve drafts, invite teammates, or update billing. `flag_kiku` is review metadata for Questions to answer, not a document write. Use the web app for uploads and workspace changes. ## Supported clients heykiku's MCP server is tested against three clients: Claude Code, Cursor, and Claude Desktop. Setup instructions for each are in the connection guide. ## How authentication works MCP uses OAuth. When you connect a client, heykiku opens a browser consent flow to grant `read` scope for your workspace. The OAuth token is workspace-scoped — a token from workspace A does not work in workspace B. OAuth is the MCP setup path. Static API keys are meant for the REST API and server-to-server fallbacks (CI jobs, custom HTTP clients) — don't wire one into your MCP client when OAuth is available; OAuth tokens are read-only by design and revocable per client. Both OAuth and REST API paths use the same role and access-tier rules. A freelancer sees general knowledge only. Employees see general and internal. Admins can also see sensitive. Owners can see owner-only. ## What MCP sees versus the web app The MCP server exposes the same knowledge your role can access in the heykiku dashboard — nothing more. The `whoami` tool shows your accessible tier, workspace, and quota. ## Revocation To revoke MCP access, go to Account → Connected apps and remove the OAuth connection for the client you want to disconnect. --- # Getting started with the REST API URL: https://heykiku.com/help/api-getting-started The heykiku REST API is one of the ways you can [connect heykiku to your stack](/features/connect), automating the parts of your knowledge workflow that don't need a human in the loop — document uploads, folder organization, listing past conversations. Workspace administration (team, billing, settings) stays in the dashboard; API keys are scoped to read or write the knowledge surface, not to manage the workspace. ## Who can use the API API access is included with the [Bloom plan](/pricing). Lower plans don't see API keys in their settings. Inside a Bloom workspace, the **owner** decides who can mint keys. By default no one but the owner can issue a key. The owner grants issuance via the team page: - **None** — can't mint keys (the default for new members) - **Read only** — can mint keys with the `read` scope - **Read + write** — can mint keys with either scope, but the member also needs upload, approve, or organize capability for `write` to be effective Freelancers can be granted issuance, but only `read` keys take effect at request time. ## Create your first key 1. Go to **Settings → API keys** in the dashboard. 2. Click **New key**. 3. Pick a scope: `read` for read-only automation; `read + write` if your integration uploads documents or organizes folders. 4. Optionally set an **IP allowlist** (CIDR notation) and an **expiry date**. 5. Click **Create**. You'll see the raw key once — copy it now. We only store a hash; we can never show it again. The key looks like `kiku_live_<48-byte-base62>`. Treat it like a password: never commit it, never paste it into chat. Anyone with the key has whatever scope you granted it. ## Make your first request ```bash curl -H "Authorization: Bearer kiku_live_..." \ https://heykiku.com/api/folders ``` A successful response is JSON. `GET /api/folders` returns the full accessible set in one call — there's no pagination on folders: ```json { "folders": [ { "id": "...", "name": "Onboarding", "accessTagId": "...", "color": null, "description": null, "documentCount": 12 } ] } ``` If you get a 401, your bearer header is missing or the key was revoked. If you get a 403 with `API_KEY_SCOPE_INSUFFICIENT`, the action needs `write` and your key is `read` only. ## Full endpoint reference The [API reference](/api-reference) links to the OpenAPI spec at `/openapi.json`. Paste that URL into Claude, ChatGPT, or Cursor to generate client code, sample requests, or ask questions about any endpoint — or point a code generator at it directly. --- # Import from Google Drive URL: https://heykiku.com/help/google-drive-import If your agency's documents live in Google Drive, you can import them without downloading and re-uploading. Imported files join the rest of your [document library](/help/document-management) and follow the same review workflow. ## What You'll Need - **Owner** or **Admin** role (to connect Google Drive) - **Upload** permission (to import files) ## Step 1: Connect Google Drive 1. Go to **Settings** → **Integrations** 2. Click **Connect Google Drive** 3. Sign in with your Google account and authorize heykiku 4. You'll return to the Integrations page with a "Connected" status showing your Google email You only need to do this once per workspace. ## Step 2: Import Files 1. Go to **Knowledge** 2. Click the **Import** button (appears next to Upload after connecting) 3. A panel slides open showing your Google Drive files 4. Browse folders or use the search field to find files 5. Check the boxes next to files you want to import 6. Select the **access level** at the bottom (required) 7. Click **Import** ## Supported File Types | Type | How It's Imported | |------|-------------------| | Google Docs | Converted to Markdown | | Google Sheets | Converted to Markdown tables | | Google Slides | Converted to Markdown | | Plain text, CSV, HTML | Imported directly | | XLSX | Parsed as spreadsheet data | PDFs, Word docs, and images from Google Drive are not supported through this import. Upload those directly using the regular [upload flow](/help/upload-first-document). ## Content Size Limit Each file can contain up to 500KB of content after conversion. Larger files will show an error during import. ## After Import Imported documents land in your Knowledge Base with **Pending Review** status. You still need to: 1. [Review the extracted content](/help/edit-extraction) 2. [Approve the document](/help/approve-document) to make it searchable Imported documents show a Google Drive icon badge in the document list. ## Re-importing a File If you import a file that's already in your knowledge base, heykiku will ask if you want to re-import it. Re-importing replaces the existing content and resets the document to Pending Review. Files already imported show an "Imported" badge in the file browser. ## Disconnecting To disconnect Google Drive, go to **Settings** → **Integrations** and click **Disconnect**. --- # Invite Team Members URL: https://heykiku.com/help/invite-team-members Your knowledge base is more valuable when your team can use it. heykiku's [four-tier access control](/features/access-control) means each person you add sees only the content their role allows, so you can invite freelancers without exposing margins or client details. Here's how to invite team members with the right access levels. ## What You'll Need - Owner or Admin role in your workspace - Email addresses of team members to invite ## How to Invite 1. Go to **Settings** → **Team** 2. Click **Invite Member** 3. Enter the team member's email address 4. Select their role: - **Admin** — Can manage users and access sensitive content - **Employee** — Standard team member access - **Freelancer** — Limited to general content only 5. Optionally adjust permission toggles: - **Allow file uploads** — Can upload documents and record voice memos - **Allow document approval** — Can approve, edit, and re-index documents - **Allow folder organization** — Can create, edit, and delete folders 6. Click **Send Invite** Permission toggles are pre-filled based on the selected role, but you can override them before sending. Changing the role resets the toggles to that role's defaults. The team member will receive an email with a link to join your workspace. ## Understanding Roles Each role determines which content tier the person can access. See [how the four access tiers work](/help/access-control) for the full breakdown. | Role | Access level | Best for | |------|--------------|----------| | Owner | Everything | Founders, partners | | Admin | Sensitive + Internal + General | Department heads | | Employee | Internal + General | Full-time team members | | Freelancer | General only | Contractors, external collaborators | ## No Per-Seat Billing Add as many freelancers as you need. heykiku uses flat pricing, not per-seat. Your monthly cost stays the same whether you have 3 freelancers or 30. --- # Lost Your Authenticator App? URL: https://heykiku.com/help/lost-authenticator Lost your phone, replaced it, or accidentally deleted your authenticator? Use a recovery code to sign in. The code disables two-factor authentication on your account so you can re-enroll on your new device. ## What You'll Need - One of the 8 recovery codes you saved when you set up two-factor authentication. They look like `A1B2-C3D4-E5F6-G7H8`. ## Step-by-Step 1. Sign in with your email and password as usual. 2. On the two-factor screen, click **Use a recovery code**. 3. Type one of your recovery codes (dashes optional, case-insensitive) and submit. 4. kiku does four things at once: - Marks that recovery code as used (it can't be reused). - Removes your old authenticator setup. - Signs you out of every active session, on every device. - Sends you back to the sign-in page. 5. Sign in again with just your password. You're back in. ## Setting Up Again Once you're back in, kiku will prompt you to set up two-factor authentication again on your new device. Follow the [setup guide](/help/setting-up-2fa) and save the new recovery codes that appear — your old ones no longer work. ## Out of Recovery Codes If you've used all 8 recovery codes and still can't sign in, contact your workspace owner. They can ask kiku support to verify your identity and reset your two-factor setup. We can't reset it for you over chat — that would defeat the point. ## What Doesn't Happen - Your password isn't reset. - Your workspace data is untouched. - Other people on your team aren't signed out — only your sessions. Recovery is a one-shot reset, not an emergency back door. --- # Manage Team Permissions URL: https://heykiku.com/help/manage-team-permissions Beyond roles, heykiku gives you fine-grained control over what each team member can do with four permission toggles. Roles set the baseline tier each person can reach — see [how the four access tiers work](/help/access-control) — and these toggles refine what they can do within it. ## The Four Permissions | Permission | What It Controls | |------------|-----------------| | **Upload** | Upload documents and record voice memos | | **Approve** | Approve documents, edit approved extractions, replace files, access Insights | | **Organize** | Create, edit, and delete folders; move documents between folders | | **Billing** | View and manage billing, change plan, buy add-ons, update payment method | Owners always have all four permissions. For everyone else, you can toggle Upload, Approve, and Organize individually. **Billing is special** — it can only be granted to Admins, and only the Owner can grant it. ## Where to Manage 1. Go to **Settings** → **Team** 2. The members table shows columns for Upload, Approve, Organize, and Billing 3. Toggle the switches for any member Each toggle change saves immediately. You'll see a confirmation toast like "Upload permission enabled" or "Billing access granted." ## Role Defaults When you invite someone or change their role, permissions reset to that role's defaults: | Role | Upload | Approve | Organize | Billing | |------|--------|---------|----------|---------| | Owner | Always on | Always on | Always on | Always on | | Admin | On | On | On | Off | | Employee | On | Off | On | — | | Freelancer | Off | Off | Off | — | You can override Upload, Approve, and Organize per person. Billing only applies to Admins — Employees and Freelancers show an em dash because the grant doesn't apply to them. ## Billing Access Billing actions are owner-only by default. If you want an Admin to handle invoices, plan changes, or add-on purchases on your behalf, toggle their Billing switch on. - Only the **Owner** can grant or revoke Billing - Only **Admins** are eligible — the toggle doesn't appear for Employees or Freelancers - The grant survives role changes within Admin tier and is revoked automatically if you tier the member down ## Tier-Down Restriction Admins can manage members at a strictly lower role tier than their own — they cannot mutate users at the same tier or above. In practice: admins can change employee and freelancer settings, but not other admins or the owner. Demoting an admin automatically revokes their Billing permission — you don't need to remove it manually first. ## Restrictions - You can't change your own permissions (prevents locking yourself out) - Owner permissions are always on and can't be toggled - Changing someone's role resets their permissions to the new role's defaults - Billing can't be set during invite — grant it after the member accepts ## Inviting with Custom Permissions When [inviting a new member](/help/invite-team-members), the invite modal shows Upload, Approve, and Organize toggles pre-filled from the selected role's defaults. You can override them before sending the invite. Billing isn't in the invite flow — grant it from the team table after the invite is accepted. --- # Notifications URL: https://heykiku.com/help/notifications The notification bell in the top-right corner keeps you informed when documents need your attention. ## How Notifications Work A bell icon appears in the dashboard header. When you have unread notifications, a badge shows the count (up to 9+). Click the bell to open the notification panel. Each notification shows: - A title and short description - When it happened (e.g., "5m ago", "2h ago") - Unread items are highlighted with a colored dot ## Document Ready Notifications When a document finishes processing and is ready for review, everyone with the **Approve** permission in your workspace gets a notification: > "[filename] has been processed and needs approval" Click the notification to go directly to that document in the Knowledge Base, with the viewer already open. ## Managing Notifications **Mark one as read:** Click any notification to mark it as read and navigate to the related page. **Mark all read:** Click the checkmark button in the panel header to clear all unread notifications at once. Notifications refresh automatically every 60 seconds, so new ones appear without reloading the page. ## Who Gets Notifications Currently, document-ready notifications go to workspace members who have the **Approve** permission. If you don't have this permission, you won't see document-ready alerts. --- # Questions to Answer URL: https://heykiku.com/help/insights-dashboard **Questions to answer** is your worklist of topics your team keeps asking that your documents don't answer yet. Open it from **Questions to answer** in the sidebar — the page lives at the `/insights` route, so you may also see it called **Insights**. It's how heykiku surfaces [your team's knowledge gaps](/features/insights) so you know exactly what to document next. ## Who can access it You need the **Approve** permission to open it. The sidebar only shows **Questions to answer** to users who have that permission. ## What gets captured A question lands here when kiku finishes a chat answer and couldn't ground it in your knowledge base — that is, the reply had no document citations, including times kiku had to refuse. Similar questions are grouped into a single topic, so "late payment policy" and "policy for late payments" become one row. At the top, kiku summarizes its replies in the last 7 days and how many grouped topics still need documentation. ## Filtering and sorting A row of status tabs filters the list: - **All** — every active topic (everything except dismissed) - **New** — not triaged yet - **Needs docs** — needs documentation - **In progress** — someone is working on it - **Answered** — closed out - **Restricted** — owner-only; hidden from everyone else Use the sort dropdown to order topics by **Recent**, **Frequent**, or **Confidence**. ## The list Each row shows: - **Topic** — the grouped question - **Tier** — the suggested access tier (General, Internal, Sensitive, or Owner only) - **Status** — where it is in triage - **Asked** — how many times it came up - **Last asked** — when someone last asked it Use **Load more** at the bottom to pull in older topics. ## Opening a question Click a row to open its detail panel. It lists the individual questions in the group — who asked and when — alongside kiku's read on the topic. If you have the **Approve** permission, the panel lets you triage: - Set the **Status** to New, Needs documentation, In progress, Answered, or Dismissed. (A topic still being grouped by the background worker shows as **Pending**; that one is read-only.) - **Rename topic** to give the group a clearer title. - Owners can **Restrict** a topic to hide it from non-owners, or **Unrestrict** to bring it back. ## Tips - Check the list weekly to catch gaps as they emerge - Frequently-asked topics are your team's most pressing documentation needs - The fastest way to clear a topic is to add a document that answers it --- # Rate limits and error codes URL: https://heykiku.com/help/api-rate-limits Every API response carries rate-limit headers. Every error response uses a consistent envelope. This article documents both so your client can be a good citizen and degrade gracefully. ## Rate limit buckets heykiku groups endpoints into buckets, each with its own per-tenant and per-account limit: - `polling` — high-frequency reads (`GET /api/documents`), the most generous bucket - `general` — other list/read endpoints (`GET /api/folders`, `/conversations`, `/access-tags`) - `upload` — `POST /api/documents`, limited per minute - `billing` — API key creation, update, and deletion, the strictest bucket The tenant limit caps total workspace traffic; the account limit caps any one user/key within that workspace. We don't publish the exact ceilings — every response includes the current ceiling for the bucket it hit, so read it from the headers rather than hard-coding numbers and your client adapts if we adjust limits. ## Headers on every response Values below are illustrative — always use what your own responses report: ``` X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 987 X-RateLimit-Reset: 1716123600 ``` `X-RateLimit-Reset` is a Unix timestamp (UTC seconds). When you hit the ceiling, the response is a 429 with a `Retry-After` header naming the wait in seconds. ``` HTTP/1.1 429 Too Many Requests Retry-After: 47 ``` ## Error envelope Every error response uses the same base shape: ```json { "error": { "code": "API_KEY_SCOPE_INSUFFICIENT", "message": "Your API key or role permissions don't grant the 'write' scope needed for this action.", "doc_url": "https://heykiku.com/help/errors/API_KEY_SCOPE_INSUFFICIENT" } } ``` - `code` is stable. Switch on it. - `message` is human-readable. Show it; don't parse it. - `doc_url` is optional — authentication errors include it; most other errors don't. - A 429 carries a `retryAfter` field (seconds) instead of `doc_url`; the same number is also in the `Retry-After` header. ## Frequently seen error codes | Code | Status | When | |---|---|---| | `API_KEY_INVALID` | 401 | A Bearer token was sent but couldn't be used — malformed, revoked, expired, or outside the key's CIDR allowlist (all collapse to one code so a probe can't confirm a real key) | | `AUTHENTICATION_REQUIRED` | 401 | No credential at all — the Authorization header is missing and there's no session | | `API_KEY_SCOPE_INSUFFICIENT` | 403 | Key doesn't have the scope this endpoint needs (e.g. a `read` key calling a `write` route) | | `PLAN_TIER_INSUFFICIENT` | 403 | Workspace plan doesn't include API access (Bloom required) | | `SUBSCRIPTION_REQUIRED` | 402 | Workspace subscription is inactive or the workspace is locked | | `MFA_REQUIRED` | 403 | Two-factor must be enabled before creating a `write`-scope key | | `VALIDATION_ERROR` | 400 | Request body or query params failed validation | | `RATE_LIMIT_EXCEEDED` | 429 | Bucket limit hit — see `Retry-After` and the `retryAfter` field | The set is open-ended. Handle unknown codes by displaying `message` and logging `code` for triage. ## What 429 means in practice When you hit a 429, wait at least `Retry-After` seconds before the next request to that bucket. The `X-RateLimit-Reset` header tells you exactly when the window rolls over — `general`, `polling`, and `billing` buckets use an hourly window; `upload` uses a per-minute window. Production clients should: 1. Inspect `X-RateLimit-Remaining` proactively and slow down before hitting zero 2. On 429, honor `Retry-After` exactly (jittered backoff is usually overkill at this scale) 3. Separate read traffic from upload traffic — they share buckets only at the account ceiling See [API versioning policy](/help/api-versioning) for what error `code` stability guarantees over time. --- # Replace a Document URL: https://heykiku.com/help/replace-file If you need to update a document with a newer version of the file, you can replace it without deleting and re-uploading. ## Requirements - The document must be **approved** (status: Complete) - The document must have been **uploaded** (not imported from Google Drive or created from a voice memo) - You need the **Approve** permission ## How to Replace 1. Go to **Knowledge** and click the document to open it 2. Switch to the **Details** tab 3. Click **Replace file** 4. Read the confirmation: "The new file will be processed and require re-approval. The document will be temporarily unavailable in chat during processing." 5. Click **Choose file** and select the replacement file 6. The upload starts immediately ## What Happens Next 1. The old file is replaced with the new one 2. The document status resets to **Pending** and goes through processing again 3. The document is temporarily unavailable in chat 4. Once processing finishes, [review the new extraction](/help/edit-extraction) and [approve it](/help/approve-document) The document keeps its folder location, access tier, and position in your knowledge base. ## Accepted File Types Same as regular uploads: PDF, DOCX, XLSX, TXT, MD, and images (PNG, JPEG, GIF, WebP). Maximum file size: 10MB. ## When to Use Replace vs. Delete and Re-upload **Use Replace** when you have an updated version of the same document (e.g., revised brand guidelines, updated pricing sheet). **Delete and re-upload** when the content is fundamentally different or you want to change the access tier. --- # Set Up Two-Factor Authentication URL: https://heykiku.com/help/setting-up-2fa Two-factor authentication adds a one-time code to your sign-in. Even if someone has your password, they can't get into your workspace without your authenticator app. ## When You Need It Workspace owners and admins who manage billing must enable two-factor authentication before they can change a plan, update payment details, or cancel a subscription. Anyone else on your team can opt in voluntarily — kiku will keep working either way. ## What You'll Need - An authenticator app on your phone (1Password, Authy, Google Authenticator, or any TOTP app) - A safe place to store your recovery codes (a password manager works well) ## Step-by-Step 1. Sign in and open **Settings** → **Security** → **Two-factor authentication**. 2. Click **Set up two-factor authentication**. 3. Open your authenticator app and scan the QR code on screen. If you can't scan, tap **Show secret key** and type the 32-character key into your app instead. 4. Your authenticator now shows a 6-digit code that changes every 30 seconds. Type the current code into kiku and click **Verify**. 5. kiku shows you 8 recovery codes. **Save them now** — you'll only see them once. Each code works for one sign-in attempt if you lose your phone. That's it. Next time you sign in, you'll enter your password and then a code from the app. ## Tips - Recovery codes are case-insensitive and you can leave the dashes in or take them out. - If you switch authenticator apps later, disable 2FA in kiku first and then re-enroll with the new app — keys can't be moved between apps. - Your recovery codes can be regenerated at any time from the same settings page. Doing so invalidates the old set. ## What Doesn't Work - SMS codes — heykiku only supports authenticator apps, which are harder to phish. - Sharing one authenticator across multiple people — the code is tied to your account. If you ever lose your phone, see [lost your authenticator app?](/help/lost-authenticator). --- # Set Up Your Workspace URL: https://heykiku.com/help/workspace-setup Your workspace is where your agency's knowledge lives. Setting it up takes a few minutes. ## Create Your Workspace 1. Sign up at heykiku.com 2. Enter your agency name 3. Choose your plan (Seed or Bloom) That's it. Your workspace is ready. ## Your 7-Day Trial Every new workspace starts on a 7-day free trial — no credit card required. You get access to all features during the trial regardless of which plan you intend to buy. As your trial gets close to ending, a banner appears at the top of the Billing page showing how many days remain. When the trial ends, the workspace requires a paid plan to continue. Your data is not deleted if you don't convert — it stays intact, and you can pick a plan at any time from [Settings → Billing](/help/billing-essentials). ## What Happens Next heykiku creates four access tiers automatically: | Tier | Who Can See It | |------|----------------| | General | Everyone, including freelancers | | Internal | Employees only | | Sensitive | Admins and owners | | Owner-only | Just you | You don't need to configure these. They're ready to use. ## Onboarding: Add Your First Content After naming your workspace, heykiku walks you through adding initial content. You can: **Import documents** — Upload PDFs, docs, or spreadsheets you already have. Choose an access level for each batch. **Record a voice memo** — Speak your knowledge and heykiku turns it into a document. Great for processes you explain verbally all the time. Google Drive import is available after setup — the onboarding screen notes: "Connect Google Drive in Settings after setup." --- # Stale Document Reviews URL: https://heykiku.com/help/stale-documents Approved documents have a review clock. Once a document passes its review interval, it shows a badge and surfaces in the review filter so approvers know to check it. ## Review States | State | Meaning | |-------|---------| | Current | Within the review interval — no action needed | | Due | Past the interval by up to one interval length | | Overdue | More than one interval length past the review date | The clock starts from the last confirmed date, the approval date, or the creation date — whichever is most recent. ## The Review Banner When you have due or overdue documents, a banner appears at the top of the Knowledge page: - Red pill for overdue ("3 overdue") - Amber pill for due ("5 due") Click either pill to filter the document list to that state. ## Who Gets Notified The daily worker runs once a day and sends in-app notifications to workspace members who have the **Approve** permission when documents transition to due or overdue status. If you don't have the Approve permission, you won't receive these alerts. ## Mark a Document as Reviewed 1. Open a document with a due or overdue badge 2. Click **Mark as reviewed** in the document panel 3. The review clock resets to today You need the **Approve** permission to confirm a document. The button won't appear if you don't have it. ## Default Review Interval The workspace default is set in **Settings** → **General** → **Default review interval**. Options range from 30 days (monthly) to 365 days (yearly). The default is 90 days. ## Tips - Check the Knowledge page weekly and use the overdue filter to catch documents that need attention - High-traffic content (rate cards, policies, onboarding checklists) should use a shorter interval than archived reference material --- # Subscription and Payment Problems URL: https://heykiku.com/help/subscription-troubleshooting ## Failed Payment When a payment fails, heykiku shows a banner at the top of the Billing page: > "Your last payment failed — please update your payment method to avoid losing access to your workspace." To fix it: 1. Go to **Settings** → **Billing** 2. Click **Update payment method** 3. Update your card in the Polar billing portal that opens If the payment still fails after updating your card, contact your bank — the issue is usually on their end. ## Workspace Locked Your workspace locks when: - A subscription is revoked (cancelled by the billing system, not by you) - A failed payment goes unresolved past the grace window When locked, you see a **Workspace locked** page instead of the dashboard. Your data is safe — nothing is deleted. ### Grace Window After a subscription is revoked, there is a short grace period (a few days) during which the workspace remains accessible. This gives owners and billing admins time to reactivate without disruption. After the grace period expires, access blocks completely. ### How to Reactivate 1. Go to **Settings** → **Billing** — this page stays accessible even when the workspace is locked 2. Click **Manage billing** to open the Polar portal and update your payment method, or choose a plan to resubscribe 3. Return to **Settings** → **Billing** and confirm your plan is active If your workspace is locked and you don't have billing access, contact your workspace owner. Employees and freelancers can't reactivate on their own. ### If You Have Multiple Workspaces The locked workspace page shows links to your other active workspaces so you can keep working while you sort out the billing issue. ## Trial Expired When your 7-day trial ends without a paid plan, the Billing page shows a prompt to choose a plan. Your data stays intact. Pick a plan and complete checkout to restore access. ## Still Locked After Updating Payment? It can take a few seconds for the billing system to confirm the change. Refresh the Billing page after a minute. If it's still showing locked after several minutes, email ask@heykiku.com with your workspace name. --- # Support Access and Privacy URL: https://heykiku.com/help/privacy-and-impersonation ## What Support Access Means The heykiku team occasionally needs to reproduce UI bugs or configuration issues that are hard to debug without seeing exactly what you see. Support access lets a team member sign in as your account temporarily to do that. By default, support access is allowed but inert — no one signs in as your account unless you report an issue and ask for help. Toggle it off to refuse all support sign-ins permanently. ## What Happens During a Session - Sessions expire after 60 minutes - The reason for the access is logged - Your data is not exported or modified - Other people on your team are not affected ## How to Toggle It 1. Click your avatar or initials in the top-right corner 2. Go to **Account** → **Privacy** 3. Use the **Allow heykiku support to access my account** toggle The change takes effect on the next page load. If a support session is already active when you turn it off, that session is signed out immediately on the next request. ## When Off When the toggle is off, any attempt by the heykiku team to sign in as your account is rejected and the session is signed out. There is no way to override this without you turning the toggle back on. ## Per-Account, Not Per-Workspace The setting applies to your account, not your workspace. Other people on your team each control their own privacy setting independently. --- # Switch Between Workspaces URL: https://heykiku.com/help/workspace-switching If you've been invited to other workspaces, you can switch between them without signing out. ## How to Switch 1. Click the **workspace name** at the top of the sidebar 2. Select the workspace you want from the dropdown 3. Click the workspace you want to switch to 4. The dashboard reloads with that workspace's data A checkmark shows which workspace is currently active. ## One Workspace If you only belong to one workspace, the sidebar shows your workspace name as a static label. There's nothing to switch. ## How to Join More Workspaces You can only join additional workspaces through an invite. There's no "Create new workspace" button after your initial signup. When an Owner or Admin from another workspace [invites you](/help/invite-team-members), that workspace appears in your switcher after you accept. ## What Changes When You Switch Everything in the dashboard reflects the active workspace: - **Chat** shows that workspace's conversations - **Knowledge** shows that workspace's documents - **Settings** shows that workspace's team and configuration - **Notifications** are per-workspace Your role and permissions may differ between workspaces. You might be an Owner in one and an Employee in another. --- # Team Member Can't See Content URL: https://heykiku.com/help/team-member-cant-see-content If someone on your team can't see content they should, here's how to fix it. Most "missing content" issues trace back to [how the four access tiers work](/help/access-control) — a role simply doesn't include the tier the document lives in. ## Check Their Role The most common cause: their role doesn't include the access tier. | Role | Can See | |------|---------| | Owner | All tiers | | Admin | General, Internal, Sensitive | | Employee | General, Internal | | Freelancer | General only | **To check someone's role:** 1. Go to **Settings** → **Team** 2. Find the team member 3. Check their assigned role **To change their role:** 1. Click on their name 2. Select a new role 3. Save ## Check the Document's Access Tier Maybe the document is in a higher tier than expected. 1. Go to **Knowledge** 2. Find the document 3. Check its access tier If a freelancer needs to see a document in the Internal tier, you have two options: - Move the document to General tier (if appropriate) - Upgrade the freelancer to Employee role (if they should see all Internal content) ## Check Document Status Documents in "Pending Review" aren't searchable yet. They won't appear in chat answers. 1. Find the document in **Knowledge** 2. Check its status 3. If "Pending Review," [approve it](/help/approve-document) ## They Still Can't See It? Verify: 1. They're in the correct workspace (people can belong to multiple) 2. They're logged in with the correct account 3. They're asking questions that should match the document If none of these work, contact support. --- # Troubleshoot MCP connections URL: https://heykiku.com/help/mcp-troubleshooting Most MCP connection issues come from authentication, workspace access, or role permissions. Start with the error your client shows, then check the matching section below. ## The client says 401 A 401 means heykiku could not verify the Bearer credential. Check: - The API key is copied exactly and still starts with `kiku_live_`. - The header is `Authorization: Bearer kiku_live_...`. - The key has not expired or been revoked. - For OAuth, the consent is still active and the token was issued for the heykiku MCP resource. If you are using an API key, create a fresh `read` key and update the client. If you are using OAuth, disconnect heykiku in the client and connect again. ## The client connects but finds no results MCP uses your current heykiku role. It only searches folders, documents, and libraries your role can see. Check: - The connected user is a member of the correct workspace. - The documents are approved or otherwise visible to that role. - The document access tier matches the user's role: freelancers see general, employees see general and internal, admins also see sensitive, and owners see owner-only. - The client is asking the right workspace if you belong to more than one. Use `whoami`, `list_folders`, or `list_libraries` to confirm what the client can access. ## The client says rate limited `ask_kiku` uses the chat quota because it calls the workspace agent. Other MCP tools use the MCP request bucket. Wait for the reset, then retry with fewer repeated calls. See [rate limits and error codes](/help/api-rate-limits) for the current limits and headers. ## Authentication still looks wrong Review [authentication and key management](/help/api-authentication). For a clean reset, revoke the old API key or OAuth connection, create a new `read` credential, and reconnect the client to `https://heykiku.com/api/mcp`. --- # Upload Your First Document URL: https://heykiku.com/help/upload-first-document Every document you upload becomes searchable knowledge. This walks through your first upload; for the full picture of folders, tiers, and the review workflow, see [document upload and management](/help/document-management). ## Supported Formats heykiku accepts: - **PDF** — Scanned or native - **Word** — .docx files - **Excel** — .xlsx spreadsheets (converted to searchable tables) - **Text** — .txt and .md files - **Images** — PNG, JPEG, GIF, WebP (text extracted via OCR) Maximum file size: 10MB per file. ## How to Upload 1. Go to **Knowledge** 2. Click **Upload** or drag files into the window 3. Select the **access tier** (who should see this content) 4. Optionally choose or create a **folder** 5. Click **Upload** ## What Happens Next 1. heykiku extracts text from your document 2. Status shows **Pending Review** 3. You can [edit the extraction](/help/edit-extraction) if needed 4. [Approve the document](/help/approve-document) to make it searchable ## Tips for First Upload Start with something useful but not sensitive: - Your revision policy - Client onboarding checklist - Brand guidelines template This lets you test the system before adding confidential content. --- # Voice Memo Capture URL: https://heykiku.com/help/voice-capture You explain things to your team every day. You can [record a voice memo](/features/voice-capture) and let heykiku turn that explanation into a structured, searchable document — no typing required. ## Why Voice? Agency owners don't write documentation. They explain. The same explanation you'd give a new hire can become a searchable document—without typing a word. ## How It Works 1. Go to **Voice Memos** in the sidebar 2. Click the **+ Record** button 3. Select an access level for who should see this 4. Click **Start Recording** and explain (2-3 minutes is ideal) 5. heykiku transcribes and structures your explanation 6. Review, edit if needed, and approve ## Choosing an access level Every voice memo needs an access tier: - **General** — Everyone, including freelancers - **Internal** — Employees only - **Sensitive** — Admins and owners only - **Owner-only** — Just you Pick the tier that matches who should be able to find and reference this knowledge. ## Tips for Good Recordings **Do:** - Speak naturally, like you're explaining to a new hire - Cover one topic per recording - Include specific examples - Mention exceptions and edge cases **Don't:** - Read from a script (sounds robotic) - Try to cover everything in one recording - Worry about "ums" and pauses (we clean those up) ## After Recording Your voice memo becomes a document in "Pending Review" status. You can: - Edit the transcription - Adjust the access tier - Add to a folder - Approve to make it searchable --- # What you can ask kiku via MCP URL: https://heykiku.com/help/mcp-tools heykiku's MCP server exposes tools for agency knowledge work once you [connect a client to your knowledge base](/features/connect). Document tools are read-only. `flag_kiku` records review metadata; it does not upload, edit, or delete documents. Every tool respects the caller's role and access tiers. If your role cannot see a document in the dashboard, your MCP client cannot see it either. ## ask_kiku `ask_kiku` is the main tool for natural questions. It sends the question to your workspace's kiku agent with only the libraries your role can access. Use it for synthesis: "What is our positioning for nonprofit clients?", "Draft a reply using our voice," or "What do we usually include in a kickoff deck?" Each call counts like a normal chat message. ## flag_kiku `flag_kiku` records that a kiku answer should show up in Questions to answer. Use it after `ask_kiku` discloses a cited disagreement between sources. Pass the `conversation_id` and `user_message_id` from the ask_kiku trailer (`assistant_message_id` is optional). All roles including freelancers can flag. Calling again on the same turn is safe. This does not upload, edit, or delete documents. ## search_knowledge `search_knowledge` searches extracted document text and returns matching documents with snippets. Use it when you need to discover source material before asking for a summary: "Search for cancellation policy," "Find documents mentioning Q4 launch," or "Which files mention Brightleaf?" ## get_document and get_documents `get_document` fetches one document by ID. `get_documents` fetches up to 20 at once. These tools are best after `search_knowledge` or `list_documents` has found the IDs. They return metadata and extracted text for accessible documents only. ## list_documents `list_documents` browses visible documents with pagination and optional filters for folder, status, and creation date. Use it for "Show recent documents," "List completed documents in this folder," or "Find documents added since Monday." Non-approvers see complete documents plus their own uploads. ## list_folders `list_folders` returns the folders your role can access, with document counts. Use it when you want the client to orient itself before asking a more specific question: "What folders can I search?" or "Which client folders are available to me?" ## list_libraries `list_libraries` shows the Mistral libraries mapped to your accessible tiers: general, internal, sensitive, or owner-only. This is mostly useful for debugging access. It does not grant new access. ## whoami `whoami` describes the authenticated caller, workspace, key or OAuth client, highest accessible tier, and quota fields. Use it when a client is connected but results do not match the access you expected.