# Pumaï — User Guide > A getting-started guide to the web interface, written for the user, with no technical > prerequisites. Application state verified on 1 August 2026. Pumaï is not a chatbot. It is an assistant that can not only answer, but **act**: browse the web, handle a mailbox, produce files, generate images, administer a server, publish content, call an API, or run a mission autonomously while you do something else. What it can do depends entirely on what **you** give it: tools, access, instructions and a control framework. This guide explains how to go from a concrete need to a reliable automation, using only the web interface. The API is presented at the end as a complementary way in. **How to read this guide.** If Pumaï is new to you, read chapters 1, 2 and 3 in order: that is the shortest path to a first automation that actually works. Chapters 4 to 6 are reference material, to consult as needed. Chapters 7 to 12 are recipes, writing advice and troubleshooting. --- ## Contents 1. [Understanding Pumaï in five minutes](#1-understanding-pumaï-in-five-minutes) 2. [First setup, step by step](#2-first-setup-step-by-step) 3. [Chat, scheduled task, Pulsar or batch?](#3-chat-scheduled-task-pulsar-or-batch) 4. [Profiles and data sharing](#4-profiles-and-data-sharing) 5. [Tools, skills, connectors and channels](#5-tools-skills-connectors-and-channels) 6. [The interface, page by page](#6-the-interface-page-by-page) 7. [Automation recipes](#7-automation-recipes) 8. [Writing a good instruction](#8-writing-a-good-instruction) 9. [Controlling actions and costs](#9-controlling-actions-and-costs) 10. [Using Pumaï through the API](#10-using-pumaï-through-the-api) 11. [Troubleshooting](#11-troubleshooting) 12. [Glossary](#12-glossary) --- ## 1. Understanding Pumaï in five minutes ### 1.1 The simplest mental model Imagine hiring a small team. Before it can work, you have to give it an identity, the means to act, instructions and a framework. Pumaï works exactly the same way: - a **profile** defines *who* works: personality, memory, rights; - a **tool** gives it a way to act: send an email, search the web, create a PDF; - a **skill** tells it *how* to go about a recurring type of task; - a **trigger** decides *when* it works: your message, a time of day, a monitoring round, or a production queue; - **action control** decides whether an action must wait for your approval; - **Activity**, **Logs** and the **Cabinet** let you verify what was done. So the usual path is: ```text Need → Profile → Tools and skills → Trigger → Optional approval → Result → Verification ``` A concrete example. "Check my server's health every morning" becomes: ```text Profile "Supervision" + an authorised SSH connection, restricted to read-only commands + a scheduled task at 08:00 + a precise diagnostic instruction + delivery by email + verification in Activity and Logs ``` Remember this sentence: **Pumaï does not guess your access.** Until you have configured a mailbox, it cannot read your messages, however politely it tells you it will take care of it. Chapter 2 exists precisely to give it those means. ### 1.2 What Pumaï actually does when you give it a task Depending on the request, Pumaï picks one of these paths on its own: 1. **answer directly**, when no action is needed; 2. **go and check** something read-only, then answer; 3. **build a plan** and split the work between several specialised agents working in parallel; 4. **use the tools** you have authorised; 5. **produce** a result, a file, an image or an external action; 6. **pause** a sensitive action to ask for your approval. You do not have to choose: the orchestrator decides, based on the meaning of your request. What *you* set is the **effort level**: the higher it is, the more Pumaï can break the work down, delegate and proofread itself — but the longer and more expensive the task becomes. ### 1.3 The areas of the interface The top menu groups the pages into six families. | Area | What it is for | |---|---| | **Dashboard** | See the state of the instance at a glance. | | **Activity** | Understand what Pumaï decided, did and produced. | | **Chat** | Ask for something now and follow the reasoning. | | **Automation** | Schedule tasks, create watches, run series production. | | **Memory & Profile** | Define the agents, their data, personality and sharing. | | **System** | Configure tools, connections, security, API and advanced settings. | Three further pages are worth knowing early: **Mail** (the assistant's mailbox), **Cabinet** (durable documents) and **To approve** (actions waiting for your decision). ### 1.4 The global automation switch At the top of the interface, an **ON/OFF** switch suspends or resumes **all** automations at once: - scheduled tasks; - Pulsar missions; - running batches. Use it before maintenance, during a configuration phase, or as an emergency brake if an automation misbehaves. It does not disable tasks individually, and it does not prevent you from using the Chat manually — it is an emergency brake, not a master switch for the application. ### 1.5 The four ways to put Pumaï to work This is the most important point in the guide, and the one that causes the most mistakes. There are four ways to trigger work, and they are not interchangeable. | | You say… | What triggers it | |---|---|---| | **Chat** | "Do it now" | You | | **Scheduled task** | "Do it every day at 8 am" | The clock | | **Pulsar** | "Keep watch, and tell me if something changes" | A regular round + a change | | **Batch** | "Make me these 36 items" | A work queue that empties | Chapter 3 covers each in detail. If you remember only one thing: **the Pulsar remembers** from one round to the next, the **scheduled task** starts from a blank page every time, and the **batch** waits for no clock — it runs straight through. --- ## 2. First setup, step by step This is the longest chapter, and rightly so: nearly every difficulty in getting started comes from an incomplete configuration. Follow the order below; it avoids the dead ends. ### 2.0 What to prepare before you start Set aside half an hour and have the following at hand: 1. **An email address dedicated to the assistant.** Not yours: one of its own. See 2.4 — this is the step that needs the most preparation, because the address must be created at a mail provider before you can enter it here. 2. **An account with an AI model provider**, unless your instance already comes with credits. This is what lets Pumaï think. Depending on your plan this may already be handled for you: check the **Credits** page. 3. **A web search key**, if you want the assistant to be able to search the internet. See 2.5. 4. **Your login details for the interface**, provided when the instance was created. You do not need all of this on day one. An assistant with no mailbox and no web access already works very well for conversation, for analysing a document you upload, and for producing files. You can add access as you go. ### 2.1 Step 1 — The owner record Open **Memory & Profile → Profiles**. At the very top of the page, before you select a profile, there is an **Instance owner** card. Fill in: - your name; - your email address; - your role or job title; - your phone number, if useful. This record describes **the person Pumaï serves**. It is shared by every profile, and it has two very concrete effects: it is the address notifications meant for you are sent to, and it is what stops the assistant from mistaking you for a customer. Do not confuse this record with a directory entry: the directory lists your contacts; the owner record is you. ### 2.2 Step 2 — The assistant and its business context Open **Memory & Profile → Assistant**. Here you describe the general framework the assistant works in: - its display name; - its main role; - its overall mission, in a few sentences; - three to six priority objectives; - its communication style; - its guardrails — what it must never do; - your company directory, if you need one. Write these fields the way you would for a new hire. "You are the assistant of a six-person architecture practice; you reply in English, politely but without flattery; you never promise a deadline or a price that is not in our documents" is far more useful than three keywords. This page describes the **general** framework. The operational settings specific to each agent (model, temperature, allowed tools) live in **Profiles**. ### 2.3 Step 3 — Profiles A profile is a complete working identity, with its own memory and rights. Do not create a profile for every small task: create one when an activity needs at least one of these: - a different personality; - a separate memory; - a particular set of tools; - a different level of autonomy; - a clearly distinct job or channel. A starting structure that works well: - **Main assistant** — Conversation type, the one you talk to in the Chat; - **Office** — Autonomous type, for mail and case follow-up; - **Watch** — Autonomous type, for monitoring and reports. Chapter 4 covers profiles and, above all, what they do and do not share. ### 2.4 Step 4 — Giving the assistant a mailbox This is the most structuring step, and the one that needs the most explanation. Take your time. #### Why its own address, and not yours An assistant that handles mail needs **its own address**, for three reasons: 1. **Traceability.** You must be able to tell at a glance what you wrote from what the assistant wrote. With a shared address that is impossible. 2. **Security.** You are entrusting it with a mailbox password. If that is your personal mailbox, you are handing over all your private correspondence, your password resets and your personal documents. 3. **Reversibility.** The day you want to stop, you close one address. You do not have to change the password to your digital life. Good practice: an address in the assistant's name on your own domain, such as *assistant@ your-domain*, or a dedicated free address if you do not have a domain. #### Creating the address and collecting its settings Create the address with the mail provider of your choice — the one hosting your domain name, or a consumer service. Then, in that mailbox's settings, check two things. **1. That IMAP access is enabled.** IMAP is the protocol that lets an outside program read a mailbox. Some providers disable it by default; you then have to turn it on, usually under a section called "external access", "mail clients" or "POP/IMAP". **2. That an app password is available.** Most serious providers no longer accept the account password for external access: they ask you to generate an **app password**, a secondary password reserved for one specific program. That is the one you will give to Pumaï. The benefit matters: it gives no access to the account settings, and you can revoke it without changing your main password. Then note the four technical settings your provider publishes in its help pages, usually under "IMAP and SMTP settings": | Setting | What it is | Usual value | |---|---|---| | Incoming server (IMAP) | The machine holding received messages | `imap.` followed by the provider name | | Incoming port | The incoming server's "door number" | **993**, over an encrypted SSL connection | | Outgoing server (SMTP) | The machine that sends messages | `smtp.` followed by the provider name | | Outgoing port | The outgoing server's "door number" | **465**, over an encrypted SSL connection | Do not try to understand these values: copy the ones your provider gives. If its help offers several options, always choose the **encrypted** variant (SSL or TLS), never the "insecure" one. #### Entering these details in Pumaï Open **System → Tools**. Tools are grouped by family; find the **mail** family and open the corresponding bundle. A tool card shows a clear badge: **✔ Configured** or **⚠ Not configured**. Expand the configuration section and fill in: - **the incoming server and port** (IMAP); - **the outgoing server and port** (SMTP); - **the account username** — usually the full email address; - **the app password** obtained in the previous step; - **the sending address**, i.e. the address that will appear as the sender. Save, then **enable** the tool with its switch. #### Deciding what it is allowed to send Two settings, on the same card, govern sending. They are the most important of the whole setup, because they are what stops an AI from writing to just anyone. **The list of authorised recipients.** This is a **right to send**, not merely a filter: an address on this list can receive a message; an address that is absent cannot. Start with your own address and nothing else. You can widen it later. **The sending policy**, which takes two values: - **Draft** — the assistant can never send anything itself. Everything it writes is placed in the mailbox's drafts, and you decide. This is the recommended setting to begin with. - **Direct send** — a message to an **authorised** address is really sent; a message to any other address **automatically becomes a draft**, and the assistant tells you plainly that it did not send. There is no configuration in which Pumaï writes to an address you have not authorised. If you empty the list, nothing goes out. #### Checking that it works Open the **Mail** page. If the configuration is correct, you will see the mailbox's real folders and messages. If the page stays empty or shows an error, go to chapter 11, "No email shows up". Then try it from the **Chat**: *"Summarise the last three messages I received."* If it summarises them, reading works. Then: *"Draft a reply to the last message, do not send it."* The draft should appear on the Mail page. ### 2.5 Step 5 — Giving it web access By default the assistant cannot search the internet. There are two ways, and they are not equivalent. **Search-engine search.** It queries a real search engine and returns a list of results. It requires an **API key** from the engine's provider — the search tool shipped with Pumaï uses the **Brave Search** API. The principle is always the same: 1. create an account on the search provider's website; 2. subscribe to its API offering (there is usually a free tier that is more than enough for an assistant); 3. copy the key it gives you — a long string of characters; 4. in **System → Tools**, open the web search tool's card, paste the key into the field provided, save, enable. **Page reading.** The tool that fetches the contents of a specific web address needs no key at all. If you do not need search but only need to follow pages you already know, it is enough. > **What is an API key?** A password meant for a program rather than a human. The provider > generates it, you paste it into Pumaï, and it identifies your account when the service is called. > Like any password, it is not shared, not put in a message, and revoked if it leaks. ### 2.6 Step 6 — Other tools: the principle is always the same You have just configured two tools. Every other tool follows exactly the same logic, which makes the rest much quicker. On the **System → Tools** page: 1. **find the tool** — tools are grouped by family: mail, web, files, memory, notifications, images, system, directory…; 2. **read its description** — it says what it really does, which prevents a lot of misunderstandings; 3. **fill in its configuration**, if it needs one. A badge shows **✔ Configured** or **⚠ Not configured**; 4. **enable it** — a disabled tool is not offered to the assistant at all; it can neither use it nor even know it exists; 5. **decide whether it must ask for your approval** — the "Ask for my approval" switch pauses every use of that tool until you decide; 6. if needed, **restrict it to certain profiles** from **Profiles → Settings**. Some examples of needs and the matching tool: | You want to… | Configure… | |---|---| | Handle email | the **mail** bundle (step 2.4) | | Search the web | the **web search** tool (step 2.5) | | Produce a PDF or a document | the **files** family — no key needed | | Generate images | the **image** family — uses your AI credits, no separate key | | Send an alert on Telegram | a Telegram **gateway** (chapter 5.6) | | Answer the phone, or call someone | a Phone (Twilio) **gateway** — a Twilio account is required (chapter 5.6) | | Administer a server | an **SSH** connection (chapter 5.7) | | Track tickets and projects | the **Renkany** bundle (chapter 5.4) | **One principle to remember: enable only what you need.** Every enabled tool is described to the assistant, which takes up room in its reasoning and offers it one more temptation. An assistant with six well-chosen tools works better than one with forty. ### 2.7 Step 7 — Choosing the level of control Open the **To approve** page. At the top is the global mode: - **Supervised mode** — the tools on which you enabled "Ask for my approval" stop before acting and file a proposal you must accept or reject; - **Autonomous mode** — everything runs without going through that queue, but everything is still logged. For a first deployment, stay in **supervised mode**, and put under approval anything that affects the outside world: sending mail, publishing, changing something on a remote server, deleting, calling an API that commits you to something. You will relax this control gradually, tool by tool, after seeing several correct runs. It is safer, and above all more instructive: the proposals you reject show you exactly where your instruction was ambiguous. ### 2.8 Step 8 — Test in the Chat before automating **Never schedule an automation you have not first run by hand.** Open the Chat, select the profile the automation will use, and give it exactly the same instruction. Check: - that the required tool is available; - that the credentials work; - that the result has the right format; - that the right recipient, target or folder is used; - that approval requests appear as expected. A test in the Chat costs two minutes. A badly configured scheduled task can get it wrong every night for a week before you notice. ### 2.9 Step 9 — Automate, then verify Now create the scheduled task, the Pulsar or the batch (chapter 3), trigger a **first manual run**, then check: - **Activity** for the business result; - the **history** of the task, mission or batch; - **To approve** for suspended actions; - **Mail** if a message was meant to go out; - **Cabinet** if a file was meant to be kept; - **Logs** if something went wrong technically. ### 2.10 The first-hour checklist - [ ] Owner record filled in - [ ] Assistant described: role, mission, style, guardrails - [ ] At least one profile created - [ ] Dedicated mailbox created at a provider, IMAP enabled, app password generated - [ ] Mail bundle configured and tested from the Mail page - [ ] Authorised recipients limited to your address only - [ ] Sending policy set to **Draft** - [ ] Web search configured if needed - [ ] Supervised mode on, approval required for external actions - [ ] One successful round trip in the Chat - [ ] A first automation created, run manually, and verified --- ## 3. Chat, scheduled task, Pulsar or batch? ### 3.1 The four modes in one sentence each - **The Chat** is a conversation. You ask, it acts, you watch, you correct. - **The scheduled task** is an appointment. At a given time, a given instruction runs — and it starts from a blank page every time. - **The Pulsar** is a patrol. At regular intervals it goes and looks, **compares with what it saw last time**, and only disturbs you if there is something new. - **The batch** is a production queue. You give it a list, it works through it end to end without waiting for any clock, and stops when the list is empty. ### 3.2 The decision tree ```text Do I want the result now, in front of me? └── yes → CHAT No. Is it a list of items to produce? └── yes → BATCH No. Do I only want to be told if something changes? └── yes → PULSAR └── no → SCHEDULED TASK ``` ### 3.3 The scheduled task in detail This is the easiest mode to understand: one instruction, one schedule, one result. Use the **Scheduler** for: - a report every morning; - a reminder on a given date; - a publication every Monday; - a routine operation every two hours; - a one-off action in the future. Three ways to set the trigger: - **Cron** — a fixed time, optionally on certain days only. "Every day at 8 am", "every Monday at 9:30"; - **Interval** — every X hours, minutes or seconds; - **Single date** — one run, at a precise date and time. **The key point: a scheduled task has no memory of its past runs.** It starts fresh every time. If you ask it to "report new messages", it has no way of knowing what was already there yesterday: it will report them all, every day. That need is exactly why the Pulsar exists. ### 3.4 The Pulsar in detail A Pulsar is a mission that lives over time. On each pass — called a **tick** — it does its job, then writes itself a short summary of what it observed: that is its **state**. On the next pass it re-reads that state, compares it with what it sees, and decides whether there is anything worth telling you. That memory between passes makes all the difference. It allows instructions like: "tell me only if a new competitor appears", "follow this incident until it is resolved", "alert me when this price drops below a threshold". **The three mission types:** - **Permanent** — it continues as long as you leave it active; - **Conditional** — it ends by itself when a condition has held long enough; - **Time-limited** — it is archived on an expiry date. **The mission's nature**, set by the *Mission nature* field: - **Watch — monitor and report** (the default). The protocol requires a fresh collection, a comparison with the previous state, and a notification when something is detected. - **Production — make artefacts**. This protocol suits a mission that *produces* something on each pass — a sheet, an image, a document — working through a list. Collection and comparison make no sense there and are not imposed, and there is no notification every time. > **Mind the effort level of a production mission.** At *Low* effort the assistant works alone and > without tools: it will therefore be unable to *make* anything. For a mission that must actually > call tools, choose *Medium* at minimum. **What a mission card shows:** the last pass, the verdict, a summary, and cumulative consumption. The **Logs** button shows the history; the **State** button shows what the mission remembers between passes — that is the first place to look when a mission behaves oddly. **Two buttons worth knowing:** - **⚡ Run now** — runs *this* mission immediately, without waiting for its next due time. It bypasses the cadence and the cool-down after an error, but it respects the stops you asked for: if automations are paused, or if the mission is paused, it refuses and tells you why. - **🏗 To batch** — appears only on a *Production* mission. It copies the mission's settings into a batch form; it creates nothing by itself. See 3.6. A **⌛** badge on a card means the mission will not run on the next wake-up, and the card says why (it is paused, its cadence is not due, or it is waiting after an error). ### 3.5 The batch in detail A **batch** produces a series of items in one go. You give it a production instruction and a list; it makes item after item until the list is empty. **What really distinguishes it from a production Pulsar** is that it **waits for no clock**. A Pulsar makes one item per round; if your instance patrols every three hours, 36 items take four and a half days. The same work given to a batch runs straight through. The second difference is less visible but just as important: **the list lives in the batch, not in the instruction**. The software keeps track of what is done and what remains — not the assistant, which could forget or get it wrong. That is what makes it possible to show a "12 / 36" bar, to re-run precisely item number 7 that failed, and to know with certainty that the batch is finished. **The two batch modes:** - **List** — you enumerate the items to produce, one per line. The batch knows the total, shows exact progress, and stops on its own when the list is exhausted. Use this mode whenever you can write the list. - **Open** — you give no list, only a **number of iterations**. The content is invented along the way. The batch stops at the requested number, or earlier if the assistant declares there is nothing left to produce. **The production instruction and the `{{item}}` placeholder.** You write a single instruction, valid for every item, and you place `{{item}}` where the item should appear: ```text MISSION — produce a colouring page of {{item}}. Black inked line art, light background, A4 portrait. File the result in the Cabinet with the tag "colouring". ``` You can also use `{{rank}}` for the item's number. If you forget `{{item}}` it is not a problem: the item is appended to the instruction in a dedicated block. **The guardrails.** A batch commits real spending, in series. Three settings bound it: - **the cost cap** — the batch stops as soon as spending reaches that amount; - **the token cap** — the same idea, counted in units of work rather than money. Useful because some model providers do not publish their prices, in which case the displayed cost stays at zero and a money cap would be useless; - **the number of consecutive failures tolerated** — beyond it, the batch stops instead of persisting. A fourth setting, the **pause between items**, helps when your provider rate-limits calls. **A batch does not start on its own.** You review the list and the estimate, then click **Start**. Likewise, after a server restart a running batch is paused and waits for you: nobody wants a machine to resume thirty paid generations by itself. **When it stops, it always says why**: queue empty, the agent declared it finished, cost cap reached, token cap reached, too many consecutive failures, quota exhausted, stop requested, automations paused, or server restart. A batch stopped by a cap keeps its remaining items pending: raise the cap and restart, nothing is lost. ### 3.6 The most common mistake You want thirty illustrations, or forty product sheets, or a series of documents. The natural reflex is to create a production Pulsar and let it run. Do not: - it only makes **one item per round**, and the round cadence is shared with all your other missions — you cannot speed it up without speeding everything up; - **nothing stops it**: when the list is finished it keeps waking up, thinking, and concluding there is nothing to do — each time at a real cost; - **the assistant** has to remember what it has already produced, and it can get that wrong. The batch was designed for exactly this case. If you already have a production mission running, the **🏗 To batch** button on its card copies its settings into a batch form: all you have to do is paste the list. Conversely, do not put a **watch** into a batch: monitoring has no list and never ends — that is a Pulsar. ### 3.7 Frequencies and cadences The general round cadence is set in **System → Dev → Pulsar cadence**. It is the rhythm at which Pumaï wakes up to look at its missions. Each mission can then refine it: - **Every tick** — on every general round; - **Hourly** or **Daily** — an extra filter; - **Custom interval**, in minutes, which takes priority. For example 360 for six hours, 1440 for a day, 10080 for a week. Avoid very short frequencies for information that rarely moves: every pass consumes credits and calls external services. A competitor watch running every five minutes learns nothing more than a daily one, and costs 288 times as much. ### 3.8 The effort level Effort sets the depth of the work: how many agents can be involved, how many back-and-forths they allow themselves, and whether they proofread. | Need | Suggested effort | |---|---| | Simple recurring check | Low | | Summary, standard analysis, producing one item | Medium | | In-depth research, important document | High | | Complex work, with critique and several specialists | Very high | Two classic traps: - **Low** is perfect for a watch that looks and concludes, but it **forbids all delegation**: work that must call tools to make something will not manage it. Use *Medium* at minimum. - **Very high** on a frequent task costs a great deal for often no benefit. Keep it for one-off, important productions. ### 3.9 Quality control before delivery All three forms — scheduled task, Pulsar and batch — offer a **Check consistency before delivery** checkbox (called *Quality control before delivery* on batches). When it is ticked, the agent that has just produced the deliverable **re-reads it** before concluding: it looks for inconsistencies — dates that contradict each other, figures that do not add up, promises that go beyond the instruction — and fixes the offending passages. It does not rewrite everything; it corrects. Use it whenever a deliverable is going to leave your organisation: a report sent to a client, a published document, a sheet handed over. It is pointless for a watch that only produces one line of verdict. This setting is **independent of the effort level**: you can have quality control at *Medium* effort, without paying for the depth of *High*. ### 3.10 Choosing delivery A scheduled task can deliver its result by email, by Telegram, in the web interface, or nowhere — in which case the result remains readable in the logs. **The channel must be configured before the first run.** Choosing "Telegram" in the form does not create the bot; choosing "email" does not create the mailbox. The form lets you select a channel that does not exist yet, and the error will only surface at run time. --- ## 4. Profiles and data sharing ### 4.1 What is a profile? A profile is a complete working identity. It has: - a type, **Conversation** or **Autonomous**; - an identity and a personality; - a "soul", meaning its voice and stance; - a durable memory of its own; - daily notes and nightly consolidations; - a directory; - open cases and an internal inbox; - a model, a temperature and a time zone; - a list of allowed tools; - an approval mode; - read rights on other profiles' data. ### 4.2 Conversation profile and Autonomous profile A **Conversation** profile is for direct exchanges. In the interface you choose it from the Chat. For Telegram or Discord, the channel relays to a chat session which itself carries a profile. An **Autonomous** profile is for scheduled tasks, Pulsars and batches: office assistant, watcher, analyst, technical supervisor. The type helps organise usage; the exact profile is still chosen explicitly in the Chat, the Scheduler, the Pulsar, the batch or the phone configuration. ### 4.3 A profile's tabs | Tab | Purpose | |---|---| | **Identity** | Business context, role, scope. | | **Soul** | Voice, stance, continuity. Change with care. | | **Memory** | Durable facts belonging to this profile. | | **Dreams** | Consolidated observations, before possible promotion to stable memory. | | **Notes** | Daily journal. | | **Directory** | Team, clients, prospects, suppliers, partners. | | **Cases** | Open matters, status, notes, resolution. | | **Inbox** | Messages left by autonomous agents. | | **Missions** | Remembered states of Pulsar missions. | | **Settings** | Model, temperature, memory, autonomy, time zone, allowed tools. | | **Sharing** | Other profiles' data this one may read. | | **User profile** | What the assistant has memorised about the person it talks to. | ### 4.4 The sharing rule between profiles By default, **profile memories are isolated**. In the **Sharing** tab you authorise the selected profile to read another profile's durable memory and recent notes. Sharing is **one-way**: ```text A is allowed to read B ≠ B is allowed to read A ``` If "Office" must consult "Main assistant"'s memory, open **Office → Sharing** and tick "Main assistant". Only tick the other direction if the need genuinely exists. Personality, soul and the consolidation journal always stay private to the profile. ### 4.5 Shared data Some data deliberately escapes that isolation: - the **owner record** is shared by the whole instance; - the **Cabinet** is a central document space shared by all profiles; - documents on the Cabinet's **Reference** shelf can be consulted by every agent; - the **Archive** shelf keeps files without making them searchable; - the main directory can serve as cross-cutting business context for autonomous profiles. Practical consequence: **do not put a confidential document in the Cabinet** of an instance used by several activities that must stay separate. Put it in the relevant profile's memory, or use a separate instance if the boundary has to be strict. ### 4.6 Allowed tools per profile In **Profiles → Settings → Allowed tools**: - an **empty** list means "all globally enabled tools"; - a **filled** list becomes a strict allowlist. A watch profile only needs the web, memory, files and notifications. It has no reason to hold a deletion or system administration tool. ### 4.7 Approval mode per profile Each profile can inherit the global setting, be **supervised**, or be **autonomous**. Keep new or risky activities supervised, and increase their autonomy after checking several correct runs. --- ## 5. Tools, skills, connectors and channels ### 5.1 The four notions These four words answer four different questions, and confusing them is a frequent source of error. | Notion | Question | Example | |---|---|---| | **Tool** | What can the agent *do*? | Send an email, create a PDF, generate an image. | | **Skill** | How should it do it *well*? | The procedure for your press review. | | **MCP connector** | Where do *extra* tools come from? | An external server exposing its own tools. | | **Gateway** | Through what *channel* does a human talk to it? | Telegram, Discord, phone. | ### 5.2 Tools A tool is an executable function. The **Tools** page lets you see what it is for, enable or disable it, check whether it is configured, require approval before each use, see its risk level, and restrict it per profile. Tools are grouped into **families** (or *bundles*): mail, web, files, memory, notifications, images, system, directory, scheduling, monitoring. Two tools deserve a special mention, because they are recent and change the way you work: **Image generation.** The assistant can create an image from a description. Three things to know: the model used is chosen in **System → Dev**, and its price is shown in the selector; the number of images produced per run is capped, to avoid unpleasant surprises; and to obtain a **consistent series** — the same style from one drawing to the next — you must give it a reference image, by providing the identifier of a Cabinet document. The random seed, on the other hand, is for **replaying** an image identically, not for making two different images consistent with each other. **File editing.** The assistant can replace a specific passage in a document it produced, rather than rewriting the whole thing. That is what makes quality control (3.9) realistic: fixing two inconsistent dates costs two edits, not a full regeneration of the document — which would risk breaking elsewhere what it repairs. ### 5.3 Skills A skill is a **reusable procedure**: the right way to carry out a type of task, written once and for all. It can define when to use it, the steps to follow, the tools required, the effort level, the expected format and the success criteria. A skill **grants no access**: the tools it mentions must still be enabled and allowed for the profile concerned. You can let the orchestrator pick the skill that fits the meaning of the request, or impose one on a mission, a task or a batch. In the input fields that support it, type `#` to insert a skill and `/` to insert a tool: the name is inserted as a coloured chip. It is a **hint** to the orchestrator, not a guarantee. ### 5.4 Ticket and project tracking (Renkany bundle) Pumaï can connect to **Renkany**, a ticket and project management tool, to read the real state of the work and act on it. This integration comes as a dedicated tool bundle, and it is **shipped disabled**: it does nothing until you have configured and enabled it. If you do not use Renkany, skip this section — the integration then has no effect and costs nothing. #### What it allows **Reading** — the assistant can consult: - tickets, filtered by status, priority, assignee, due date, project; - a ticket's detail, with its comment thread and attachments; - the list of projects and the directory of people; - workload per person; - service-level compliance; - time spent; - the activity log. **Writing** — it can: - create a ticket in a project; - change a ticket's status, which is how a ticket is moved to "resolved"; - reassign it to someone else; - add a comment to it; - attach a file to it. **What it deliberately does not allow:** no deletion is exposed — not tickets, projects, comments or attachments — and the assistant can neither create a project nor replace a project's member list. Those remain human actions. #### Configuring it Open **System → Tools**, find the matching family, and fill in: - **your tracking instance's API address**; - **the access token** — the equivalent of an API key, obtained from your tracking tool; - **the write policy** (see below). Then enable the bundle. > **Use a token with company-admin rights.** A more restricted token answers *partially* — it > returns only the tickets it may see — **without saying so**. You would then get wrong counts, with > no error message at all. #### The write policy Three values, to be chosen deliberately: - **No writing** (the default) — read-only. Enabling the bundle from the Tools page therefore gives you consultation and nothing else: writing requires a separate, deliberate action. - **Comments only** — the assistant can annotate, not modify. - **Full write** — it can create, change status, reassign, comment, attach. > **Creating a ticket sends an email to the people assigned** and consumes quota. It is never a test > operation: try read-only first. #### Two points to watch **Internal notes.** When the assistant adds a comment, it writes an **internal note** by default, visible to your team only — not to the client. This is the opposite of the usual behaviour of such tools, and it is deliberate: an agent writes a working note; it does not send text to a client unless asked. For a comment genuinely visible to the client, you must ask explicitly. When reading, internal notes are flagged as such, each on its own line, with a warning. This is the number one risk of the integration: a client brief that copied an internal note would be an unrecoverable incident. **Scope.** The company concerned is determined by the token, never by a request from the assistant: one Pumaï instance corresponds to one client, hence one company. An important consequence to keep in mind when reading a result: **an empty count may mean "outside my scope", not "nothing to report"**. The assistant reminds you of this on every count. ### 5.5 MCP connectors MCP is a standard that lets an external server expose its own tools. Plugging in an MCP connector adds, in one go, a set of tools Pumaï did not have. The safe path: 1. add the server; 2. leave it **disabled** while you check its origin and configuration — that is how it arrives, and the safeguard is deliberate; 3. fill in its variables or its authorisation; 4. enable the server; 5. discover the tools it exposes; 6. enable only the ones you need; 7. set their approval requirement and per-profile access. A local server executes code on Pumaï's machine. Only enable servers you trust, and keep MCP tools that write or act externally under approval during the first runs. ### 5.6 Gateways A gateway is a conversational way in, to talk to Pumaï other than through the web interface: - **Telegram** — a bot, a list of authorised users, an associated session; - **Discord** — a bot, authorised users, optionally a channel, a session; - **Phone (Twilio)** — a real phone number. See below. A gateway does not replace a business tool: chatting with Pumaï on Telegram does not configure email sending. #### The phone, in detail This is the most impressive and the most misunderstood capability: **your assistant can pick up the phone, and it can call out.** It is not an answering machine — it is a real-time voice conversation, held by the same assistant you meet in the Chat, with its memory and its tools. **The provider is Twilio**, and there is no other: Pumaï relies on their real-time voice service for inbound calls, and on their API for outbound ones. So you need to open a Twilio account and buy a number there. It is a paid service, billed per minute and **independent of your AI credits**: you will pay for two things, telephony at Twilio and reasoning at your model provider. **What you need to gather:** | Item | Where to find it | |---|---| | **Account SID** | On the Twilio dashboard. Starts with `AC…`. | | **Auth Token** | On the same dashboard. It is a secret: treat it like a password. | | **A Twilio number** | Bought from their console, in international format: `+1…`. | | **A public HTTPS address** | The address through which Twilio reaches **your** instance. It must be reachable from the internet. | | **The answering profile** | The Pumaï profile that will handle incoming calls. | **The step that trips people up most often: the public address.** Twilio is an outside service; to put a call through to you, it must be able to reach your instance from the internet. An instance only reachable on your local network will never receive a call. If your instance is hosted and already has a public address, use it; otherwise you have to expose your machine temporarily through a tunnel. **The two directions do not require the same work:** - **Receiving a call** needs the whole configuration above, public address included, plus one setting on **Twilio's side**: in your number's settings, the Voice webhook must point to the address shown on the Gateways page, ending in `/v1/voice/incoming`. Copy it verbatim. - **Placing a call** only needs the account, the token and the number. It is simpler, and it is often the better place to start in order to validate your credentials. **Two tools, not to be confused**, which you enable like any other from the Tools page: - **`place_call`** — starts the call and returns immediately. The assistant does not know what was said; it only knows the call went out. For "let them know", "confirm it to them". - **`call_and_wait`** — starts the call **and waits for it to end** in order to report what was said. This is the one you want when you expect an answer: "call them and ask whether Thursday's appointment still stands". A call lasts tens of seconds: this tool is slow by nature, and the engine accounts for that in its time limits. Both take a **number in international format**, a **one-sentence objective** and optionally some **context**. Write the objective the way you would tell someone you are handing the phone to: "find out whether Tuesday's delivery is confirmed" beats "call the supplier". > **A phone call is irreversible.** Unlike an email draft, a placed call cannot be taken back. Keep > both tools **under approval** until you have seen several calls go correctly, and only then open > up autonomy. ### 5.7 SSH connections The SSH page registers the remote servers the assistant may use. Each target has an alias, a host, a port, a user, key or password authentication, an optional privilege-escalation permission, and **a list of allowed commands**. Predefined profiles — Health, Security, Maintenance, Logs, Containers — let you start from a sensible list. Always prefer a minimal allowlist over "all commands". --- ## 6. The interface, page by page ### 6.0 What appears on every page The top bar lets you suspend or resume all automations, change the interface language, switch between light and dark theme, return to the Dashboard, and log out. Several pages show a **collapsible help banner** explaining the page in a few lines: read it the first time, it often saves a question. A **Support** button at the bottom of the interface lets you send feedback; describe the page, the time and the expected result, so the corresponding run can be found in the Logs. ### 6.1 Dashboard An overview: actions awaiting approval, saved conversations, active scheduled tasks, active missions, knowledge sources, open cases. It is an orientation page, not an audit log. ### 6.2 Activity **This is the best page to answer "what has my assistant done?".** It brings together: - mailbox activity; - the actions, reports, answers and files produced; - actual consumption; - an estimate, clearly labelled as such, of the human time saved; - a **mission timeline**, presented as a narrative: objective → what happened → result; - the state of each profile; - pending proposals; - open cases. You can change the period, and filter by profile or by origin — Chat, scheduled task, mission, batch. Click a row to expand the detail. ### 6.3 Mail The mailbox used by the assistant: received, sent, drafts. It depends on the mail bundle configured in chapter 2.4. It is a read-only control view. There is exactly one write action: when a **draft** prepared by the assistant is shown, a button lets you actually send it, after you have read it. This explicit human approval is not subject to the authorised-recipient list — you are the sender. Correspondents are labelled automatically: Management, Team, Client, Supplier, Assistant or External, and the direction of a message (received or sent) is determined by the addresses, not by the folder name. ### 6.4 Cabinet The Cabinet centralises the instance's durable files: documents you upload, reports and deliverables filed by the assistant, items to be sent, archives. **Two shelves:** - **Reference** — the document is indexed; the assistant can find it and cite it in an answer; - **Archive** — the file is kept, but does not feed search. **What a document's card tells you:** - its **origin** — where it really came from: a conversation, a named watch mission, a scheduled task, a batch, an email send, or you. It is reliable classification that neither you nor the assistant has to type in; a filter lets you show one origin only; - whether it is **indexed or not**. Watch this one: a document filed under *Reference* whose text could not be extracted — an image, a scanned PDF — is indexed nowhere, and **no mission can find it**. The page now says so explicitly; - its **identifier**, displayed and copyable in one click. This is the value you paste into a mission to designate a reference image; - its **tags**, editable from the expanded card; - its **provenance** (you or the assistant), its intended recipient and its status: to send, sent, superseded. Visual documents show a thumbnail. **The Cabinet is durable; a run's workspace is temporary.** If a produced file must remain available after the conversation, explicitly ask for it to be filed in the Cabinet. ### 6.5 Showcase The Showcase turns the instance's real journal into a presentable page: actions, output, watches, decisions, files, cases handled. It is **private by default**. The **Publish** button creates a public link containing a token: anyone with that link can view the page without a password. Identities and email addresses are masked there, and files are not downloadable publicly — the page attests that they exist without handing over their contents. Still, review the page before sharing it. You can write the public introduction, publish, copy the link, go private again, or regenerate the link to invalidate the old one. ### 6.6 Chat The Chat is for asking a question, requesting an action, attaching a document or an image, following the reasoning and the tools used, retrieving deliverables, interrupting a running job, and returning to an earlier conversation. Before sending: choose the **profile**, choose the **effort**, attach the files, and describe the expected result **and its destination**. Changing profile starts a new session, to avoid mixing contexts. A few commands: - `/task ` — force handling as a complex task; - `/new` — new session; - `/profile` — show the user profile; - `/remember ` — ask for something to be memorised. Type `/` to insert a tool or `#` to insert a skill. Images and documents you paste into the Chat can be reused by the assistant: it can analyse them, attach them to a send, or use them as a reference for generating an image. ### 6.7 To approve Every action suspended before execution. For each one you can **Approve**, **Reject**, choose **Later**, mark **I'll handle it**, correct some arguments before approving, or add a note. Check the recipient, the target, the attachments and the parameters of an irreversible action first. A selector lets you see proposals from **all profiles**, and a button clears expired proposals — that operation is reversible, nothing is deleted. ### 6.8 Scheduler To create a task: 1. click **New task**; 2. give it a readable name; 3. write the complete instruction; 4. choose the category: reminder, appointment or mission; 5. choose Cron, Interval or Single date; 6. set the schedule; 7. choose delivery; 8. select the profile — this is required; 9. choose the effort; 10. tick **Check consistency before delivery** if the result leaves your organisation; 11. create, then trigger a first manual run. From the list you can run, edit, disable, re-enable, delete and view the history. The **Calendar subscription** section provides ICS addresses for reminders and appointments. Do not share them: they expose your schedule. Regenerating the token invalidates every previous subscription. ### 6.9 Pulsar To create a mission: 1. click **New mission**; 2. give it a name; 3. choose Permanent, Conditional or Time-limited; 4. write what to observe, compare and report; 5. set the frequency, or a custom interval in minutes; 6. choose the **nature**: Watch or Production; 7. choose the effort — *Low* for a simple watch, *Medium* at minimum for production; 8. optionally impose a skill; 9. tick quality control if needed; 10. select the profile; 11. save; 12. click **⚡ Run now** for a first trial. Each card shows the last pass, the verdict, a summary and cumulative consumption. The **Logs** and **State** buttons show the history and the memory kept between passes. The **Wake the heartbeat** button at the top of the page wakes the general mechanism: it does not force cadences. A mission that is not due will still not run — and the page tells you, mission by mission, what will actually be executed. To run *one* mission off-cadence, use its **⚡ Run now** button. A well-written Pulsar clearly distinguishes what existed on the previous pass, what is new, what has disappeared, what justifies an alert, and when it should stay silent. ### 6.10 Batches The third entry in the **Automation** menu. The first two are clocks; this one is a work queue. **Creating a batch** — the **New batch** button: 1. a **name**; 2. the **nature**: *List* or *Open* (see 3.5); 3. the **production instruction**, with `{{item}}` where the item should appear; 4. depending on the nature, the **list of items** (one per line) or the **number of iterations**; 5. the **profile**; 6. the **effort** — *Medium* at minimum if the items must call tools; 7. a **skill**, if you have a suitable one; 8. the **cost cap** and/or the **token cap**; 9. the number of **consecutive failures tolerated**; 10. the **pause between items**, if your provider rate-limits calls; 11. **quality control before delivery**, if the result must be flawless. Save. **The batch does not start on its own**: review the list and the estimate, then click **Start**. **Following a batch.** Its card shows a progress bar such as "12 / 36", the actual spending, an estimate of what remains to produce, an approximate finish time, the item in progress, the number of failed items, and — if it has stopped — the exact reason. The estimate of what remains is computed from the items **already** done. Until something has been produced, nothing is shown: an invented figure would be worse than no figure. **Acting.** The **Items** and **Log** buttons expand the detail: each item with its state, the files it produced, and a **Retry** button to re-run precisely the one that failed. A retried item reproduces exactly the same item, never "the next one". The **Pause** and **Stop** buttons suspend production; remaining items are kept pending. Finished batches are grouped in a collapsed section at the bottom of the page. ### 6.11 Assistant Two uses: 1. the **general business configuration**: identity, mission, objectives, style, constraints, directory; 2. the **mission plans**: objective, audience, horizon, resources, channels, indicators, phases and checkpoints. A mission plan is not a scheduled task: it describes an objective in several phases and steers activity over time. It can be inactive, active, paused or archived. The page also shows **open cases**. A case tracks a matter through to closure; on its own it triggers nothing. ### 6.12 Memory This page manages a profile's persistent knowledge: select the profile, add a text or a file, classify the source, test a search, manage conversation segments and explore the knowledge graph. It is organised in three tabs: - **Memories** — the list of what is memorised, conversations and documents, with their state (memorised or set aside). The "See the facts" button shows the elements that are **actually retrievable**, which are the unit of search — not the whole conversation. A test bar lets you try a search and see the score obtained. - **Knowledge graph** — the entities and links the assistant has extracted. Clicking an entity opens its card. - **Maintenance** — the housekeeping operations. Each states what it does **and what it costs**, because some trigger one model call per conversation. The three levels of memory, so you know what you are handling: the immediate conversation history, summaries of older exchanges, and long-term memory queried by similarity of meaning. If you are not comfortable with these notions, stick to adding sources and testing search: those are the only two operations you need day to day. ### 6.13 Profiles The place where roles and data are separated (chapter 4). Start with the owner record at the top, then create or select a profile and go through its tabs. When creating one: a readable name, a stable lowercase identifier, the right type, long-term memory enabled if the profile must search its memories, and the time zone matching its working hours. In **Settings**, a low **temperature** suits factual work, a higher one creative work. The global model remains the best choice until a specific need justifies an exception. ### 6.14 Tools The native, custom and MCP capabilities, grouped by family. Filters let you search by family, type, exposure, risk, approval and state. For everyday use: open a tool's card, read its description, configure it, enable it, choose its approval setting. The code and file-tree sections are for advanced users; to create a tool without writing code, use the **Studio**. ### 6.15 Gateways For Telegram or Discord: create the bot on the platform, get its token, list the authorised users, choose an existing session, create the gateway, test it, check that it is connected. For the **phone**, choose the **Phone (Twilio)** type, then: 1. open a Twilio account and buy a number there; 2. note the **Account SID** (it starts with `AC…`) and the **Auth Token** from their dashboard; 3. enter them here, together with the **number** in international format (`+1…`); 4. fill in your instance's **public HTTPS URL** — the one Twilio will reach it on from the internet; 5. choose the **profile that answers** incoming calls; 6. create the gateway. The interface then shows the **Voice webhook** to copy **on Twilio's side**, into your number's settings: it is your public URL followed by `/v1/voice/incoming`; 7. test an **outbound** call first — it does not depend on the webhook, and it validates your credentials without depending on your instance being reachable. If outbound calls work but inbound ones do not, the cause is nearly always the same: your instance is not reachable from the internet, or the webhook was not pasted on Twilio's side. ### 6.16 SSH To add a server: **New connection**, an unambiguous alias, the host, port and user, key or password authentication, privilege escalation only if necessary, a command profile, then remove the commands you do not need. Save, and first test a **read-only** command from the Chat. The page configures the connection; the task itself is then created in the Chat, the Scheduler or a Pulsar. ### 6.17 Credits The balance, consumption and history, when your instance runs on supplied credits. If that mode is not active, the page tells you so. ### 6.18 Studio The Studio creates a custom tool from a guided interview: describe the purpose, the inputs and the output; answer the questions; review the generated code; declare the sensitive capabilities needed; provide test arguments; test in a sandbox; save first as a trial version; only promote to stable after validation. A tool that uses the shell, the network or sensitive writes should stay under approval. Earlier versions can be restored. ### 6.19 Skills A library, an editor, guided creation, a comparative "with / without" sandbox, and a global switch. For a skill to be useful, pay particular attention to: a clear **trigger** ("when the user asks…"), an ordered **procedure**, the **tools** required, the expected **input** and **output**, and verifiable **success criteria**. The sandbox really runs two variants of the same task and therefore consumes credits. Use a representative task, then compare quality, number of steps and cost. ### 6.20 API access The main key, named secondary keys, revocation, examples and access to the interactive documentation. A secondary key is shown in clear **only when it is created**: copy it immediately into a password manager. Renewing the main key cuts off every integration using the old one. ### 6.21 MCP connectors Several ways to add one: official catalogue, search in a public registry, import, manual command, remote server with a key or delegated authorisation. Servers arrive **disabled**. After enabling one, review each discovered tool, here and then in **Tools**. ### 6.22 Dev The technical settings console: providers and models, agent limits, effort levels, memory, Pulsar cadence, Showcase, and various advanced options. Three things to know: - **the model selectors show each model's price.** This is not a detail: changing model can triple the cost of a production run with nothing else in the interface changing; - **some fields are read-only**, with a badge explaining what drives them. Those are the ones the effort level imposes: changing them here would have no effect, and the page says so rather than letting you believe otherwise; - **this page rewrites the instance's configuration.** If you do not know exactly what a setting does, do not change it. ### 6.23 Logs The technical diagnostic view: runs, their origin, status, duration and consumption; agents and sub-agents; tool inputs and outputs; model calls made outside a run; phone calls; sessions and authentication events. A run that came from the Chat carries a 💬 icon that opens the matching conversation. A running job can be interrupted from this page. Simple rule: **Activity** to check the work, **Logs** to understand an error, a slowdown or a cost. ### 6.24 Cases Cases — also called open loops — are the matters not to be forgotten: a client request, a pending quote, an incident, a follow-up, an action to finish. A case has a title, a description, a contact, a priority, a status, a last action and notes. It can be updated, closed or cancelled. Closing records the resolution; deletion should stay exceptional, because it erases the trace of the follow-up. --- ## 7. Automation recipes ### 7.1 Triaging urgent emails **Goal:** watch the mailbox, classify messages, alert only when necessary. 1. Configure the mail bundle (2.4). 2. Define the authorised recipients. 3. Create an autonomous profile called "Office". 4. Limit its tools to mail, memory, cases and notifications. 5. Create a permanent **Pulsar**, nature *Watch*. 6. Choose an interval of 15 or 30 minutes. 7. Effort **Low**. 8. Run it once by hand, then check Mail, Activity and Logs. ```text Goal: spot the messages that need a quick reaction. Scope: the inbox, unread messages from the last 24 h. Treat as urgent: an outage, a quote request, a client chasing us, a message from a directory contact marked as priority. On each pass: compare with what you retained last time. Only report what is NEW since the previous pass. If there is nothing new: stay silent, send no notification. Remember: the identifiers of the messages already reported. ``` ### 7.2 Sending a daily summary **Scheduled task**, Cron at 6 pm, "Office" profile, effort **Medium**, delivery by email, quality control ticked. ```text Goal: a recap of the day just ended. Scope: messages received and sent since 00:00, cases modified today. Produce: a summary of at most 10 lines, then a list of pending items. Never ask again for an action already handled: if a case is closed, do not raise it. If nothing happened, say so plainly — do not invent activity. Deliver: by email to the owner. ``` That last instruction matters: without it, a report can invent a "quiet day" where it simply failed to read the data. ### 7.3 Publishing weekly **Scheduled task**, Cron on Monday at 9 am, a dedicated profile, effort **High**, quality control ticked, publishing tool **under approval** at first. ### 7.4 Checking a server's health An SSH connection limited to read-only commands, a "Supervision" profile, a **scheduled task** at 8 am, effort **Medium**, delivery by email or Telegram. ```text Goal: detect a problem before it becomes an incident. Scope: the server named . Check: disk space, load, memory, expected services, recent log errors. Alert if: disk above 85 %, an expected service is stopped, or errors repeat. Produce: a 5-line status, then detail only if something is wrong. Run no command that modifies anything. ``` ### 7.5 Producing a report, filing it, sending it In the **Chat**, effort **High**: ```text Goal: a monthly activity report. Scope: the month just ended. Produce: a structured document, then convert it to PDF. File the PDF in the Cabinet, Reference shelf, tags "report, monthly". Then send it to the owner as an attachment. ``` Note the order: produce, file, **then** send. Asking for the send first often yields an email with no attachment. ### 7.6 Chatting from Telegram Create the bot on Telegram, get its token, create the gateway with the list of authorised users, associate a session carrying the right profile, test. ### 7.7 Watching a price until a threshold A **Conditional** Pulsar, nature *Watch*, effort **Low**, 6-hour interval. ```text Goal: tell me when the price of drops below . Source: . On each pass: re-read the page, extract the price, compare it with the remembered price. Report: only if the price has dropped below the threshold, or fallen by more than 10 %. Remember: the last observed price and its date. Stay silent in every other case. The mission is complete once the threshold alert has been sent. ``` ### 7.8 Producing a consistent image series This is the textbook case for a **batch**. 1. Put an image in the **Cabinet** to serve as the style reference, and copy its identifier from its card. 2. Create a batch, nature **List**. 3. Paste the list of subjects, one per line. 4. Write the instruction with `{{item}}` and the reference image's identifier. 5. Effort **Medium**, a sensible cost cap, 3 failures tolerated. 6. Save, review, **Start**. ```text MISSION — produce an illustration of {{item}}. Style: match exactly the style of reference image . Format: square, light background. File the produced file in the Cabinet, Archive shelf, tag "series". ``` Watch the first three items before walking away: if the style is wrong, pause, fix the instruction, and restart. That is far cheaper than discovering thirty-six failed images. ### 7.9 Reviewing tickets every week **Scheduled task**, Cron on Friday at 5 pm, a dedicated profile, effort **Medium**, quality control ticked, ticket-tracking bundle in **read-only**. ```text Goal: a weekly review of the state of the work. Scope: all projects, the week just ended. Produce: resolved tickets, open tickets by priority, those past their due date, and workload per person. Remember that scope depends on permissions: an empty count may mean "outside my scope", not "nothing to report". Never copy the content of an internal note. Deliver: by email to the owner. ``` ### 7.10 Placing a phone call First configure the **Phone (Twilio)** gateway (5.6), then enable `call_and_wait` on the Tools page, **under approval** for the first trials. From the **Chat**: ```text Call +1XXXXXXXXXX. Objective: find out whether the delivery scheduled for Tuesday is confirmed, and at what time. Context: order no. 1234, placed on the 12th, contact is in the shipping department. Report back what was said, without interpreting it. ``` The action will appear in **To approve** before going out. Check the number — unlike an email, a call cannot be taken back. Once the call ends, the assistant reports what was said; the detail is also in the **Logs**, in the phone calls section. For a simple message with no answer expected, `place_call` is enough and returns immediately. ### 7.11 Plugging in an external service Add the matching MCP server, leave it disabled, check its origin, fill in its access details, enable it, then enable only the useful tools, under approval at first. ### 7.12 Integrating an API with no tool or connector Use the **Studio**: describe the API, its inputs and its output, and let the guided interview produce the tool. Test it in the sandbox before saving it. --- ## 8. Writing a good instruction ### 8.1 The structure that works A good instruction contains six elements: 1. **Goal** — what must be obtained; 2. **Scope** — sources, period, account, server, folder; 3. **Rules** — what is allowed, what is forbidden; 4. **Criteria** — thresholds, quality, success conditions; 5. **Output** — format, length, structure; 6. **Destination** — screen, email, Cabinet, publication, or nothing. ```text Goal: … Scope and sources: … You may: … You must never: … Consider the task successful if: … Produce: … Deliver the result: … If there is nothing to report: … ``` ### 8.2 For an automation that runs without you An automation cannot ask you a question at the right moment. Remove the ambiguities **before** scheduling it: - name the recipients; - name the accounts and connections; - give numeric thresholds; - say what to do if information is missing; - say whether to stop, stay silent, or produce a partial report; - say whether an action should be **proposed** or **executed**. ### 8.3 For a Pulsar Always add: what counts as new, what counts as an alert, what to remember from one pass to the next, how to avoid reporting the same thing twice, when to stay silent, and when the mission is complete. ### 8.4 For a batch A batch's instruction is **the same for every item**. So write it in the singular, placing `{{item}}` where the item should appear, and **never refer to what came before**: no "the next one", no "like the previous one", no "continue the series". Each item must be producible on its own, and reproducible identically if it fails. Also specify where to file the result. An item produced and not filed ends up in a temporary workspace. ### 8.5 For an action that leaves your organisation Explicitly write the recipient or target, whether you want a **draft**, a **proposal** or a **real send**, the attachments, the account to use, and what to do if the target is not authorised. "Draft an email" does not mean "send it". "Publish" asks for a real action and may trigger an approval request. --- ## 9. Controlling actions and costs ### 9.1 A cautious start 1. test in the Chat; 2. put external tools under approval; 3. choose a moderate frequency; 4. stay at Low or Medium effort; 5. trigger a first manual run; 6. check the result; 7. increase autonomy gradually. ### 9.2 Where to look | Question | Page | |---|---| | What did the assistant actually produce? | Activity | | Is an action waiting for my approval? | To approve | | Did the email really go out? | Mail | | Is the file kept? | Cabinet | | Did the task run? | Scheduler history | | What does the Pulsar know? | Pulsar → State | | How far along is the production? | Batches | | Why did the run fail? | Logs | | How much did it consume? | Activity, Logs, or Credits | ### 9.3 Avoiding unnecessary spending - do not run a round every five minutes for a daily signal; - use Low effort for simple checks; - impose a proven skill: it reduces trial and error; - limit each profile's tools; - give clear stopping criteria; - pause failing missions rather than letting them retry; - disable advanced features you do not use; - use the global switch during maintenance; - look at the price shown in the model selector before changing model. ### 9.4 A batch's caps A batch is the only mode that commits spending in series while you are away from the screen. Always give it at least one cap: - a **cost cap** if your provider publishes its prices; - a **token cap** in all cases — it works even when the displayed cost stays at zero because no price is published; - a number of **consecutive failures** tolerated, so that a recurring problem stops production instead of repeating it. A batch stopped by a cap has lost nothing: raise the cap and restart. ### 9.5 Keeping secrets safe - **never** put a key, a token or a password in a message, a memory or the Cabinet; - use only the configuration fields provided in Tools, MCP, Gateway or SSH; - create one secondary API key per integration, never a single shared key; - revoke the key of an integration you remove; - regenerate a public Showcase link if it has spread too widely; - limit the authorised users on Telegram and Discord; - limit the email recipients; - always grant the minimum permissions. --- ## 10. Using Pumaï through the API Everything configurable in the interface has an API representation, and the main actions can be triggered from another application. ### 10.1 Creating a key **System → API access → New key**. Name it after the integration that will use it, and copy the displayed secret immediately: it will never be shown in clear again. Then send the key in your request headers: ```http Authorization: Bearer YOUR_KEY ``` ### 10.2 Common uses Send a message and receive the answer; open a progressive response stream; manage sessions; choose a profile and an effort; manage scheduled tasks; manage profiles; query memory; list tools; handle pending proposals; use the endpoint compatible with existing OpenAI clients. The **API access** page provides examples already adapted to your instance's address, and a button opens the full interactive documentation. ### 10.3 Good practice One key per application and per environment; never a key in public source code or in a browser; an explicit profile in every call; a session identifier kept when you want to maintain context; a fresh context for a different user or a different line of business; handling of timeouts and long-running jobs; immediate revocation if a key is compromised. The interface remains the best way in for configuring profiles, tools, security and connections. The API is then how you drive Pumaï from a CRM, a client portal, a script or a business application. --- ## 11. Troubleshooting ### "The assistant says it cannot use a tool" Check in this order: does the tool exist in **Tools**? is it **enabled**? is it **configured**? does the profile allow it? is the connector that provides it active? is an approval pending? A disabled tool is not merely blocked: it is not offered to the assistant at all. ### "The scheduled task does not run" Check the global switch, then that the task is active, then the schedule, the days and the profile's time zone. Click **Run** for an immediate test, then open its history and the Logs. ### "The Pulsar reports nothing" Click **⚡ Run now** — not the general wake button, which does not force cadences. Open **State** and **Logs**. Check the frequency, the custom interval, that the mission is active and not expired, and that the instruction actually defines what counts as an alert. **A silent verdict is often normal:** a good Pulsar does not repeat information that has not changed. ### "The Pulsar consumes too much" **Low** effort, longer interval, a more precise skill, a narrower scope, an explicit silence rule and a completion criterion. Pause the mission while you investigate. If the mission **makes** something in series, it is not a setting that needs changing: it is a batch that needs creating (3.6). ### "The batch does not start" A newly created batch waits for you to click **Start** — that is deliberate. Then check that automations are not paused, and that items are still pending. After a server restart, a running batch is paused: restart it yourself. ### "The batch stopped on its own" Its card always shows the reason: queue empty, cost cap, token cap, too many failures, quota exhausted, stop requested, automations paused, restart. In the case of a cap, raise it and restart: the remaining items are kept. ### "No email shows up" Is the mail bundle configured and enabled? Are the incoming settings the ones your provider publishes? Is IMAP access actually enabled at the provider? Is the password you used an **app password**, rather than the account password? Test, then check the Logs, which give the mail server's exact error message. ### "The email is not sent" First check that it is not simply a **draft** — that is the most frequent case, and it is the expected behaviour if the sending policy is *Draft* or if the recipient is not on the authorised list. Then look at **To approve**, then at the outgoing settings. Finally, check your instruction: "draft an email" does not ask for a send. ### "The file has disappeared" A file left in a run's workspace is temporary. To keep it, explicitly ask for it to be filed in the **Cabinet**. ### "The assistant cannot find a document" In the Cabinet, check that it is on the **Reference** shelf *and* that it is marked **indexed** — a scanned PDF or an image is not, and therefore stays unfindable. In Memory, check the profile, the source's state and its indexing. Try a search with words close to the content. Finally, check that long-term memory is enabled for that profile, and sharing if the source belongs to another profile. ### "Telegram or Discord does not answer" Test the gateway, check its connection state, its token, the authorised user or channel identifier, and the associated session. Check the Logs. ### "An SSH connection fails" Check the host, port, user, key or password, then that the requested command is on the allowed list. Test a simple read-only command first. ### "An automation is misbehaving" 1. switch the global control to **OFF**; 2. interrupt the running job from the Logs; 3. disable the task, mission, batch or tool responsible; 4. put the profile back into supervised mode; 5. inspect Activity and Logs to understand; 6. fix the instruction, retest in the Chat, then resume. --- ## 12. Glossary **Agent** — A working instance that reasons and uses tools. One request may involve several. **API key** — A password meant for a program rather than a human. **App password** — A secondary password, generated by your mail provider for one specific program, revocable independently of the account password. **Authorised recipient list** — The assistant's right to send. An address not on the list cannot receive a message. **Batch** — A production queue that works through a list of items without waiting for any clock, and stops when the list is empty. **Cabinet** — The instance's durable, central document space, shared by all profiles. **Bundle** — A coherent family of tools: mail, web, files, images… **Case (open loop)** — A matter to follow through to resolution. **Effort** — The level of depth, delegation and proofreading applied to a run. **Gateway** — An external channel through which a human converses with Pumaï: Telegram, Discord or the phone. **Phone gateway (Twilio)** — The gateway that gives the assistant a real phone number. It answers incoming calls and can place calls itself. Twilio is the only supported provider, and its per-minute billing comes on top of the AI cost. **Item** — One unit of production in a batch. **Long-term memory** — Search by similarity of meaning across indexed conversations and documents. **MCP** — A standard that lets an external server expose its tools to Pumaï. **Profile** — A working identity, with its own personality, memory, tools and autonomy. **Pulsar** — An autonomous mission that wakes at regular intervals and remembers what it saw on the previous pass. **Quality control** — A re-read of the deliverable by the agent that has just produced it, before delivery. **Run** — The complete handling of a request or an automation, from start to delivery. **Scheduled task** — An action executed on a schedule, an interval or a date, with no memory of previous runs. **Session** — A conversation thread that keeps its context and its profile. **Showcase** — A publishable page presenting the instance's real activity and output. **State (of a Pulsar)** — What the mission retains from one pass to the next. It is what lets it say "that was not there last time". **Tick** — One pass of a Pulsar mission. **Token** — The unit in which an AI model's work, and therefore its cost, is counted. **Tool** — An executable function that lets the agent read, produce or act. **Workspace** — A run's temporary space. Anything that must last goes into the Cabinet.