Files
Open Files in the main navigation to see the files and connections Istota can reach for you. On a phone, open Places beside the page title to choose a location.
Places and access
My files is your own workspace folder. Linked folders, room folders and group folders appear when they are available to your account. Room membership is checked again on each request, so leaving a room removes access to its folder.
The first sidebar section after Pinned is named after the assistant. It holds My files, Rooms, Groups, Configuration, Skill instructions, Scripts and Prompt files. Rooms and Groups open a list of your room or group folders in the main area, each with its access for a task; choose one to browse it, and the path above the listing leads back to the list. Linked folders and Connections have their own sections below it.
In the sidebar, a small robot icon marks each place a task in your private room can reach, pinned files and folders included. A place without the icon is visible to you only. In the Rooms list, a room folder's access applies only to that room's own tasks. Each list in the assistant's section (Rooms, Groups, Configuration, Skill instructions, Scripts, Prompt files) says under its caption, with the same icon, what a task can do with everything in it; Groups says nothing there when your group folders differ in access. Hover over the icon to see what a task can do there and where: a room folder only in its own room, a group folder in a shared room only when everyone there is in the group. The reach panel below the folder toolbar explains it in full.
The folder toolbar shows the selected place's access for a task in a private room: Read-write, Read-only, Via skill or No access, with the robot icon when a task can reach the place. These badges describe task access; they do not mean that the web page can edit the files. Open “How Istota reaches your files” to see the selected place's access in a private room, on your own turn in a shared room, and on a guest's turn or a task nobody asked for. The disclosure also says what the robot icon means, where files are stored and whether sandboxing limits task access.
Personal memory is not loaded into shared-room prompts, even when your own turn can read your files. A room folder is available to tasks in that room only. Group folders show “Depends on room” for shared-room turns: every reader must belong to the group, with no guests or other bots present. A room linked to a group can use only that group. Connections such as Google Drive are reached through a skill during a task. Folders someone shared with Istota from their own server are listed under Shared folders and reached through the shares skill; they cannot be browsed here (Sharing with Istota). Talk attachments are not listed: a task gets a copy of the files it was sent and nothing else from the bot's Talk folder. On a local workspace, files posted in Talk are in the room's own folder.
Browsing
Choose a folder to open it. The breadcrumbs return to its parents, and the address bar keeps the current place and folder so browser Back, Forward and reload work. Files in My files, linked folders, room folders and group folders open in the shared viewer. Access is checked again when you open a file.
Hidden files are off by default. Show hidden remembers your choice in this browser. Symbolic links are labelled and cannot be opened or followed. Other special entries, such as sockets, are also inert.
A PDF in the viewer zooms with a pinch, a double tap, Ctrl+wheel or a trackpad pinch, the +, - and 0 keys, or the zoom buttons, and the page is redrawn sharp at the new size. This works in the iOS app too, where the page itself does not zoom.
A CSV or TSV file opens as a table, with Rendered and Source to switch between the table and the raw text, as for Markdown. Click a header to sort by that column; a column of numbers sorts by value. Drag a column's edge to resize it, use the arrow keys on it, or double-click it to fit. Web and mail addresses in cells are links. The table shows the first 2,000 rows of the preview and says so when there are more. A malformed file is still shown rather than refused.
A large directory shows at most 2,000 entries and a notice. This is a slice of the directory's enumeration order, sorted with folders first; it is not necessarily the alphabetically first 2,000 entries. Entries whose names cannot be represented as text are skipped and counted below the listing. A folder that cannot be read shows an error and a Retry button.
Adding files
In My files, use Upload or drop files onto the listing. Files upload one at a time, with progress and any error beside each file. Uploads keep existing files: a repeated name gets a number. The default size limit is 100 MB per file. New folder creates a folder in the location shown in the dialog. Group folders work the same way for every current member, except the All users folder, which only admins can change (see Group files). Room folders, linked folders and Drive have no upload or new-folder controls.
Editing text files
A text file in My files has Edit in its row menu, including a file made in the host folder on the Mac or uploaded. A file counts as text by the viewer's rule: valid UTF-8 with no NUL bytes, and at most 1 MB. Binary files, larger files and links stay view-only. Text files in a group folder are editable by every current member, under the same rules; GROUP.md and memories at the top of the folder are not, and the notebook is edited on the Groups page. Room folders, linked folders and Drive are not editable here.
If the file changed since you opened it, in the host folder or by a task, the save is refused and your text stays in the editor. A file's permissions are kept, so a script stays executable, and a file written with Windows line endings is saved with them. Files in the bot's config folder open in the configuration editor instead, which checks them before saving.
Quick notes
New note, at /istota/notes/new/ and in the installed web app's icon menu, opens an editor with no title field. Choose the folder first in Settings → Preferences → Quick notes; the folder is inside My files, and one that does not exist yet is created by the first note. With no folder set, the editor asks for one.
The note saves as you type and when you press Done. It is a Markdown file named from its first line, with Markdown markers removed and cut to 60 characters; a note with no usable first line is named by the date and time. A repeated name gets a number. Until the server has the text, the draft stays in the browser, so going offline or being signed out loses nothing, and signing back in returns you to the note. If the note was changed, moved or deleted elsewhere, or the folder setting changed, saving stops and the editor offers Save as a new note. A note is limited to 256 KB.
Configuration files
Configuration, in the assistant's section of the Files sidebar, opens a list of your own config files in the main area: USER.md, CRON.md, TASKS.md and HEARTBEAT.md, each with what it does and its size. Skill instructions opens a list with one row per skill you can use. A skill's file is added to that skill's own instructions whenever it loads. Edit opens the file in an editor. You can only reach your own files.
A save checks the file the way Istota reads it, and nothing is written when the check fails:
CRON.mdandHEARTBEAT.mdare parsed first. A TOML error, a job with a bad field or a command job saved by someone who is not an admin is listed under the text, and your text stays in the editor.- A skill's file is limited to 32 KB, the size above which Istota does not load it. The safety skills take no user instructions and are not listed.
- If the file changed since you opened it, usually because Istota wrote to it, the save is refused and your text stays. Reload to see the other version. If Istota is writing the file at that moment, try again.
Jobs saved in CRON.md change at the next CRON.md sync, not at once. A file that is not a plain file, such as a link a task left in its place, cannot be edited.
Scripts
Scripts and Prompt files are entries in the assistant's section of the Files sidebar. Each opens a read-only list of those files under /Users/{user_id}/{BOT_DIR}/scripts/; Prompt files appears once the folder holds one. Each row shows the file's description, the scheduled jobs or heartbeat checks that reference it, and when it was modified. Choose a name to preview it. The row's menu has Open and Reveal, which opens its folder in My files.
A missing file that a job or check names appears above the list, with the jobs that name it, and the sidebar entry carries a warning. A missing prompt file is listed under Prompt files. Used by shows whether a job is disabled, suspended, not yet synced or admin-only. “Not used by any job” means no command or prompt-file reference was found in your scheduling files. Inline prompts that mention a script are counted separately; a mention does not mean the script runs. Relative paths in commands and references from other scripts are not tracked.
When writing a script, put a one-line description in a comment or module docstring immediately after the shebang, before any code:
#!/usr/bin/env python3
# Emails the weekly project summary.
Without a shebang, put the description first. Existing scripts without one still appear as “No description”. Prompt files under scripts/prompts/ use their first non-empty line. Descriptions are shortened to 200 characters. The view reports when its listing is incomplete or a source could not be read; reload the page after editing files to refresh it.
Nextcloud and Drive
On a Nextcloud-backed workspace, My files shows a Shared marker when Nextcloud reports a share. Open in Nextcloud appears when the file is shared with your account. If share information is unavailable, browsing still works and a notice explains what is missing. A disconnected Nextcloud folder shows an error instead of an empty listing.
Your connected Nextcloud account appears under Connections. Folders open in Files, and files open in the same viewer as your workspace files, read through your personal connection. The viewer and the file's menu both have Download and Open in Nextcloud, so a file type with no preview can still be saved or opened there. If the connection has expired or been revoked, the viewer says so and links to Connections to sign in again. Only you can see this view: it uses your personal connection, which tasks never use. The toolbar shows Only you instead of an access badge, and a note above the listing says the same without anything to open. Istota's Nextcloud skill uses the bot's own account. To work on a file with Istota, put a copy in My files.
Google Drive has My Drive and Shared with me views. Open folders to browse them and choose Load more when more items are available. Files open in Google Drive in another tab. If Drive access is off or the connection needs attention, use the Connections link to restore it.
Pins
Open the three-dot menu beside a file or folder and choose Pin to add it to Pinned at the top of Files. The same menu has Download for files and a provider link when available. Pins are references, not copies. Open a pinned file or folder from there, or remove its pin with the adjacent remove button. A file that was deleted or is no longer accessible stays in the list as Unavailable so you can remove it yourself. You can keep up to 50 pins.
Istota sees the references on your next private-room task and can read them when needed. Pinning does not load a file's contents. Pins follow the personal-memory rule: they are absent from shared-room member and guest turns, and present in email thread rooms that run as your correspondence. Unavailable references stay in the prompt until you remove their pins.