📥 Project Sources: every file that came in, by day

Every project has two zones:

• Sources — every file you or your team supplied: files from a Telegram group, a Google Drive folder or a folder on this computer, files a Drive source imported once with Import files once…, and files you add yourself. On disk this is the sources/ folder of the project.
• Workspace — everything else. You and your agents organise it freely: there are no mandatory folders. Scheduled reports go to reports/<YYYY-MM>/ by convention, unless you ask for another place.

The project also has a hidden .amba/ folder where AMBA keeps its own state (what it learned about the project, older versions of your files). You do not need to open it.

In the file tree the two zones are shown as Sources (by source, then by day) and Workspace (a free tree).

---

1. Agents can never change Sources

Agents, processes, the Office engines, model-written scripts and test runs can read Sources but can never write, move, rename or delete anything in Sources or in .amba/. This is enforced by the app on every file action, in every mode — it is not a setting and no permission or approval can turn it off. A result is always saved as a new file in the workspace.

Files that live outside the project (a Drive folder, a folder on your computer) are copied into Sources; the originals stay where they are and are never touched.

2. You can still edit a source file

Sources are read-only for agents, not for you. If you correct a file yourself (for example in Excel):

• AMBA keeps the previous version. In the file tree the file shows a history icon; ⋯ → File history lists the older versions.
• Figures and reports that relied on the old version are marked to be checked again. The day of that file shows "… changed after the report "…" used it — run it again" with a Run again button.

Deleting a source file from the app is also possible; its content stays in the history.

3. Final is a state, not a folder

A file is final when a process delivered it or when you mark it yourself (Mark as final in the file tree; Unmark final to undo). Final files carry the Final badge wherever they are saved. You can still keep your own final/ folder if you like.

4. Kinds of files

When a file arrives, AMBA records for it, without the AI:

• the business day it belongs to (from its content, title, file name, the message sent with it and its arrival time);
• its kind, for example "Sales report" or "Costs", recognised from the file's structure (sheet names, columns, title);
• who sent it, and whether it is a duplicate or a newer version of a file already received;
• which process run or report used it, and when.

The first time a new file structure arrives, AMBA asks once — What kind of file is this? — with suggestions (also in your Telegram chat). Name it, and from then on files of that kind are recognised by themselves. In the demo shop, naming two kinds was enough for all 43 files to be classified. Project settings → File kinds lets you rename or merge the kinds AMBA learned.

5. Each source is an item in the file tree

Under Sources in the file tree, each source is its own item — for example Telegram · Accounting group, Drive · Branch reports, Folder · Invoices — with a health dot: green is Receiving, amber needs attention (no files yet, paused, a temporary error), red means the source stopped receiving (Needs sign-in again, the bot cannot read the group, the folder is gone). Files you add yourself are under Uploaded by you.

Under each source are its days, each with a small badge on the right that counts that source's files only:

Badge	Meaning	Click it for
✓	The day's files were used in a report	which report, when, which run
N unknown kind	Files of a new layout	What kind of file is this? — answer it right there
N need a date	Files whose day is unclear	choose the day (or Not tied to a day)
⚠	Files but no report yet, or a file changed after its report	the reason and a fix: Run now, Run again, Open process, Sign in again

Hover a badge to read the reason; every fix is at most two clicks from the tree. A file of unknown kind also carries a small dot. ⋯ → File history on a file shows the reports that used it and the older versions AMBA kept.

Opening a source

Click a source to open it as a tab, like a file (close it, reopen it, switch between tabs). The main area is the Ingestion history, newest first, by day. Each time AMBA checks the source is one line with its time and one result:

• ✓ N new files — with the file names and who sent them (Telegram group) or "from the folder";
• – no new files — consecutive checks with nothing new are folded into one line: no new files (17 times);
• ⚠ skipped N files — with the reason: same content as a file already there, too large (Telegram lets bots download at most 20 MB), a file type AMBA does not read (installers), an Office temporary file (~$…), a Google file that cannot be downloaded;
• ✗ Could not download N file(s) — tried again on the next Fetch files — a network drop, a brief Telegram or Google failure, a file locked by another program. AMBA remembers the file and every later Fetch files tries it first; when it comes through the new line says N downloaded on retry and the file still lands on the day it was sent. After 5 failed retries the line names the file with a Retry button. Files skipped on purpose (duplicates, too large, unsupported types) are never retried.
• ✗ an error — for example Google needs you to sign in again, with a Sign in again button; a repeated error is folded: Repeated 12 times since 6:00 AM.

Files of unknown kind have a Classify button in their line. Scroll down (or Show more) for older checks. AMBA keeps this history for 90 days.

The Setup button at the right of the tab opens or closes the setup pane; AMBA remembers your choice. The pane depends on the kind of source:

• Telegram group — Bot, Group (by name), Ask for the date when unclear (you, someone in the directory, or nobody), Ask the file kind on Telegram.
• Google Drive folder — Account (sign in again right there when Google asks), Folder (by name), Also take the files already there.
• Folder on this computer — Path, Also take the files already there.

Every kind also has File arrangement. AMBA reads every subfolder level of a Drive folder or a folder on this computer; a folder that links back up is read once, and one Fetch files takes at most 5,000 files (press it again for the rest).

Below: Check, Pause / Resume and Remove source.

How files are arranged

File arrangement decides the folders a source's files land in, inside its own folder:

• By day (default) — one folder per business day (2026-10-07);
• By month — one folder per month (2026-10);
• By year — one folder per year (2026);
• Keep the original folders (Drive folders and folders on this computer only) — the same folders as in the source, for example Kế toán/Tháng 10/….

In the day, month and year arrangements a file without a known date goes to No date yet. The business date of each file, its kind, the day badges and what processes read do not depend on the arrangement. With months, years or the original folders the day badges also show at the top of the source's tab (By business day), and a month or year folder in the tree carries the badge of its days.

A new arrangement applies to new files. When you change it in the setup pane and save, AMBA asks whether to Rearrange now the files already there or apply it to New files only. Rearrange… (the source's ⋯ in the tree or in its tab) does the same at any time: pick the arrangement, see N files will move into M folders, confirm. Two files with the same name in one folder keep both: the second gets (2). Facts, reports, file history and mentions in chats follow the files to their new place. Only the source's own folder changes; agents and processes still cannot move files in Sources.

Removing a source and its files

A source owns the files it brought in — files it received by itself and files imported once alike. Remove source asks first, with Also delete the N file(s) this source brought in (with their size) ticked:

• Ticked: those files, the earlier versions AMBA kept and their ingest history are deleted for good. If facts or reports used these files, the dialog says they will need re-checking.
• Unticked: AMBA stops taking new files; what it brought stays in Sources under Removed source · <name>. That item opens as a tab too and has Delete to remove it later.

A source a process still reads cannot be removed — remove it from that process's Fetch files steps first. If a file is open in another app and cannot be deleted yet, AMBA names it and tries again the next time it starts. Files under Uploaded by you are still deleted one by one, as before. Agents and processes can never delete anything in Sources.

Uploaded by you opens as a tab too, listing the files you added by time.

Fetching files

AMBA does not read sources in the background: files come into Sources when you ask, or when a process that reads them runs.

• Fetch files at the top of a source's tab (or ⋯ → Fetch files on the source in the file tree, also on right-click) reads that source once. While it runs the button shows Fetching files…; then a result line appears (Fetched 2 new file(s), No new files) and the history gains a Fetched by hand entry. Telegram groups that share a bot are fetched together.
• ⋯ → Fetch files from all sources at the top of Sources fetches every active source of the project, one after the other.
• Processes made in an earlier version with a "when files arrive" start (now an Advanced step) still start when fetched files arrive. New processes run on their Schedule.
• Telegram keeps messages only about 24 hours. When a Telegram source has not been fetched for more than 20 hours, its tab says Last fetched N hours ago — Telegram keeps messages only about 24 hours and its dot turns amber; after 24 hours it turns red: messages older than 24 hours may be gone. Fetch at least once a day.
• Processes fetch with a Fetch files step. A process reads a source only when one of its Fetch files steps runs — on its schedule, with ▶ Run whole process, or with ▶ (Run this step now) on that step. It is exactly like pressing Fetch files: it fetches now and does not wait; to look again later, add Wait until and another Fetch files step. The history shows Fetched by process …. In Test step by step, sources are read only when you tick Fetch files before testing.
• AMBA still sends no questions on Telegram (file dates and kinds are asked in the app), and a process's Telegram conversation with the owner is paused (Paused (needs automatic fetching)).

Adding a source

⋯ at the top of Sources has Upload Files and Add source ▸ Telegram · Drive · Folder. Add source opens a new tab with the setup pane; when you click Add source, the source appears in the tree and the tab becomes its tab. Adding a Telegram group also saves the group in the project directory (once), so processes can name it.

Importing files once from Drive. Open a Google Drive source and click Import files once… at the top of its tab: the Drive browser opens on the source's folder, and you can go anywhere in that Google account to pick files by name. They are copied into that source, sorted by day and classified like the files it receives; its ingestion history shows Imported once: N file(s). No Drive source yet? Add one first.

Files imported from Drive earlier. One-shot imports used to sit in a separate item. When you open the project, AMBA moves them into the Drive source of the same Google account when there is exactly one (processes and recorded facts follow). Otherwise they appear under Imported from Drive (earlier) with Move into a source… and Delete.

Files not tied to a day (a staff list, a price list) are in the source's No date yet folder or under Uploaded by you. See also Processes → Sources and file sources.

When a Telegram source receives nothing

The source's tab says why, and its setup pane offers the fix:

• Keychain access not allowed — macOS blocked AMBA from reading the bot token. Press Allow keychain access; when macOS asks, choose Always Allow and enter your Mac password. Check or Fetch files retries once too.
• Not connected / Bot token no longer valid — press Enter the bot token again and paste the token from @BotFather.
• Bot uses a webhook — the bot sends its messages to another service. Turn off webhook (after a confirmation) lets AMBA read the group; only do it if you no longer use that service.
• Another program reads this bot — stop the other program (or another running copy of AMBA), or choose another bot in Bot. Choosing another bot reads the group again from the start.
• No group in the list — add the bot to the group (or send a message or /start in the group), then press Reload.

Only a short network or Telegram outage shows Temporary error — press Fetch files to try again.

6. Projects created before version 0.5.13

Older projects used three fixed folders (input/, workings/, output/). On the first start after the update, AMBA moves them once:

• files in input/ that arrived from a source go to that source's day in Sources;
• everything else in input/ goes to sources/uploads/, keeping its sub-folders;
• workings/ and output/ stay where they are, as ordinary workspace folders.

A one-time notice, Incoming files now live in Sources, says how many files were moved. Processes, saved facts and file references are updated in the same step, so nothing has to be set up again. If a file could not be moved (for example a file with the same name but different content already exists in Sources), nothing is moved and the notice gives the reason.