Skip to content

Personal AI agent for macOS, Windows, Linux, Android & iOS. Set a goal, it works alone: coding (Skales Code), desktop + browser automation, autonomous scheduled Tasks. Teams of agents and humans across paired desktops. Agent2Agent, MCP, computer use, voice, local LLMs (Ollama), Agent Skills (SKILL.md). 26 AI providers, BYOK. No Docker, no terminal.

The readme stops linking a blog that is being switched off, and the guide catches up with the app

Mario Simic93302eec9458
diff --git a/README.md b/README.md
index 7b5c0ed..a67cccc 100644
--- a/README.md
+++ b/README.md
@@ -124,7 +124,7 @@ The private AI that lives on your computer and does real work, not just chat.
<p>If you find this useful, a ⭐ helps others discover it</p>
<p>
- <a href="https://docs.skales.app">Documentation</a> · <a href="https://getskales.app">Blog</a> · <a href="./CHANGELOG.md">Changelog</a> · <a href="https://github.com/skalesapp/skales/discussions">Community</a>
+ <a href="https://docs.skales.app">Documentation</a> · <a href="./CHANGELOG.md">Changelog</a> · <a href="https://github.com/skalesapp/skales/discussions">Community</a>
</p>
diff --git a/docs/skales-guide.html b/docs/skales-guide.html
index 7da44eb..5c20743 100644
--- a/docs/skales-guide.html
+++ b/docs/skales-guide.html
@@ -18,6 +18,26 @@
If a release adds something worth explaining, explain it in the CHAPTER FOR
THAT FEATURE. That is the change the guide should carry.
+
+ ---------------------------------------------------------------------------
+ STRUCTURE (12.7.2). One file, on purpose, and the reasons are load-bearing:
+
+ * fetch_skales_docs (actions/orchestrator.ts) reads exactly
+ public/docs/skales-guide.html and splits it on h1-h3. Splitting the guide
+ into chapter files would take the app's own manual away from the app.
+ * docs.skales.app and the public repo carry this single file too.
+
+ So the chapters are inside it. Every chapter is a <section data-lead> landing
+ page followed by its own <section id>s; the sidebar is the table of contents;
+ one chapter is on screen at a time; the search at the top of the sidebar
+ indexes every heading and every paragraph of every chapter, including the
+ ones that are not currently shown. Pure CSS and inline script, nothing
+ fetched, so it behaves identically inside the app and in a browser, online or
+ off.
+
+ Adding a chapter: add a <div class="section-label" data-chapter="x"> plus its
+ links to the nav, and give the sections the same ids. Everything else - the
+ routing, the search index, the prev/next footer - follows from the nav.
-->
<html lang="en">
<head>
@@ -54,11 +74,11 @@
.wrapper { display: flex; min-height: 100vh; }
nav {
- width: 260px;
- min-width: 260px;
+ width: 280px;
+ min-width: 280px;
background: #0f0f12;
border-right: 1px solid var(--border);
- padding: 2rem 1.25rem;
+ padding: 1.5rem 1.1rem 3rem;
position: sticky;
top: 0;
height: 100vh;
@@ -69,7 +89,7 @@
display: flex;
align-items: center;
gap: 0.6rem;
- margin-bottom: 2rem;
+ margin-bottom: 1.1rem;
text-decoration: none;
}
nav .logo-mark {
@@ -87,37 +107,128 @@
nav .logo-text { font-weight: 700; font-size: 1.1rem; color: var(--text); }
nav .logo-version { font-size: 0.7rem; color: var(--muted); margin-left: 2px; }
+ /* Search */
+ .search-box { position: relative; margin-bottom: 1.25rem; }
+ .search-box input {
+ width: 100%;
+ background: var(--surface);
+ border: 1px solid var(--border);
+ border-radius: 0.5rem;
+ color: var(--text);
+ font: inherit;
+ font-size: 0.85rem;
+ padding: 0.5rem 2.2rem 0.5rem 0.7rem;
+ outline: none;
+ }
+ .search-box input::placeholder { color: #6b6b74; }
+ .search-box input:focus { border-color: rgba(132, 204, 22, 0.45); }
+ .search-box .search-key {
+ position: absolute;
+ right: 0.5rem;
+ top: 50%;
+ transform: translateY(-50%);
+ font-family: monospace;
+ font-size: 0.7rem;
+ color: #6b6b74;
+ border: 1px solid var(--border);
+ border-radius: 4px;
+ padding: 0 0.3rem;
+ pointer-events: none;
+ }
+ .search-box input:focus ~ .search-key { display: none; }
+
+ #search-results { display: none; margin-bottom: 1rem; }
+ body.searching #search-results { display: block; }
+ body.searching #toc { display: none; }
+ .search-count {
+ font-size: 0.65rem;
+ font-weight: 600;
+ letter-spacing: 0.1em;
+ text-transform: uppercase;
+ color: var(--muted);
+ margin: 0 0 0.5rem 0.5rem;
+ }
+ .search-hit {
+ display: block;
+ padding: 0.45rem 0.7rem;
+ border-radius: 0.5rem;
+ text-decoration: none;
+ border: 1px solid transparent;
+ }
+ .search-hit:hover, .search-hit.sel { background: var(--surface-light); border-color: var(--border); }
+ .search-hit .hit-title { display: block; font-size: 0.83rem; color: var(--text); font-weight: 500; }
+ .search-hit .hit-where { display: block; font-size: 0.68rem; color: var(--accent); text-transform: uppercase; letter-spacing: 0.06em; }
+ .search-hit .hit-snip { display: block; font-size: 0.73rem; color: var(--muted); line-height: 1.45; margin-top: 0.15rem; }
+ .search-hit mark { background: rgba(132, 204, 22, 0.22); color: var(--text); border-radius: 2px; padding: 0 1px; }
+ .search-empty { font-size: 0.8rem; color: var(--muted); padding: 0.5rem 0.7rem; }
+
+ /* Chapter switcher: the part that was missing. Every chapter is one click
+ away from every other chapter, from anywhere in the document. */
+ .chapter-switch { display: flex; flex-direction: column; gap: 1px; margin-bottom: 1.25rem; }
+ .chapter-switch a {
+ display: flex;
+ align-items: center;
+ gap: 0.55rem;
+ padding: 0.4rem 0.6rem;
+ border-radius: 0.5rem;
+ color: var(--muted);
+ text-decoration: none;
+ font-size: 0.83rem;
+ transition: background 0.15s, color 0.15s;
+ }
+ .chapter-switch a:hover { background: var(--surface-light); color: var(--text); }
+ .chapter-switch a.current { background: var(--accent-glow); color: var(--accent); font-weight: 600; }
+ .chapter-switch .num {
+ font-family: monospace;
+ font-size: 0.7rem;
+ opacity: 0.6;
+ min-width: 1.1rem;
+ text-align: right;
+ }
+
nav .section-label {
font-size: 0.65rem;
font-weight: 600;
letter-spacing: 0.1em;
text-transform: uppercase;
color: var(--muted);
- margin: 1.5rem 0 0.5rem 0.5rem;
+ margin: 1.25rem 0 0.4rem 0.5rem;
+ }
+ nav .group-label {
+ font-size: 0.62rem;
+ font-weight: 600;
+ letter-spacing: 0.08em;
+ text-transform: uppercase;
+ color: #6b6b74;
+ margin: 0.9rem 0 0.25rem 0.75rem;
}
nav a {
display: block;
- padding: 0.45rem 0.75rem;
+ padding: 0.35rem 0.75rem;
border-radius: 0.5rem;
color: var(--muted);
text-decoration: none;
- font-size: 0.875rem;
+ font-size: 0.85rem;
transition: all 0.15s;
}
- nav a:hover { background: var(--surface-light); color: var(--text); }
- nav a.active { background: var(--accent-glow); color: var(--accent); font-weight: 500; }
+ nav #toc a:hover { background: var(--surface-light); color: var(--text); }
+ nav #toc a.active { background: var(--accent-glow); color: var(--accent); font-weight: 500; }
main {
flex: 1;
+ /* A flex item defaults to min-width:auto, which means it refuses to get
+ narrower than its widest unbreakable child. On a phone that turned one
+ table into a page-wide horizontal scroll. */
+ min-width: 0;
max-width: 820px;
padding: 3rem 3.5rem;
margin: 0 auto;
}
- /* Hero */
+ /* Hero, shown on the front page only */
.hero {
- margin-bottom: 3.5rem;
+ margin-bottom: 2.5rem;
padding-bottom: 2rem;
border-bottom: 1px solid var(--border);
}
@@ -145,6 +256,9 @@
/* Sections */
section { margin-bottom: 3rem; }
+ /* Jumping to a section must not park its first line under the fixed
+ Contents button on a phone. */
+ main section[id] { scroll-margin-top: 1rem; }
h2 {
font-size: 1.35rem;
@@ -165,6 +279,7 @@
align-items: center;
justify-content: center;
font-size: 0.9rem;
+ flex-shrink: 0;
}
h3 {
@@ -177,6 +292,22 @@
p { color: var(--muted); margin-bottom: 0.75rem; }
strong { color: var(--text); font-weight: 600; }
+ /* Cross-references. Scoped to running text rather than set on every `a`,
+ because the cards, the chapter list and the search hits are links too and
+ are styled as surfaces. Without this a link inside a paragraph came out
+ in the browser's default blue, and purple once it had been followed. */
+ main p a, main li a, main td a, main .then a, main .do a, .tip a, .warn a {
+ color: var(--accent);
+ text-decoration: none;
+ border-bottom: 1px solid rgba(132, 204, 22, 0.35);
+ }
+ main p a:hover, main li a:hover, main td a:hover, main .then a:hover, main .do a:hover, .tip a:hover, .warn a:hover {
+ border-bottom-color: var(--accent);
+ }
+ ul, ol { color: var(--muted); }
+ main ul, main ol { margin: 0.75rem 0 1rem 1.35rem; }
+ main li { margin-bottom: 0.4rem; font-size: 0.9rem; }
+
/* Cards */
.card-grid {
display: grid;
@@ -207,6 +338,7 @@
}
.badge-beta { background: rgba(59,130,246,0.15); color: #60a5fa; }
.badge-alpha { background: rgba(245,158,11,0.15); color: #fbbf24; }
+ .badge-new { background: rgba(132,204,22,0.15); color: var(--accent); }
/* OS install */
.os-grid {
@@ -361,105 +493,332 @@
display: flex;
justify-content: space-between;
align-items: center;
+ gap: 1rem;
+ flex-wrap: wrap;
}
footer a { color: var(--accent); text-decoration: none; }
footer a:hover { text-decoration: underline; }
- @media (max-width: 900px) {
- nav { display: none; }
- main { padding: 2rem 1.5rem; }
- .os-grid { grid-template-columns: 1fr; }
+ /* ---- Chapter landing page ------------------------------------------- */
+ .chapter-lead { margin-bottom: 3.5rem; }
+ .lead-kicker {
+ font-size: 0.68rem;
+ font-weight: 700;
+ letter-spacing: 0.12em;
+ text-transform: uppercase;
+ color: var(--accent);
+ margin-bottom: 0.5rem;
+ }
+ .chapter-lead h2 {
+ font-size: 2rem;
+ border-bottom: none;
+ padding-bottom: 0;
+ margin-bottom: 0.6rem;
+ display: block;
}
+ .lead-intro { font-size: 1rem; max-width: 620px; }
- /* TEIL 7 (12.5.7): the guide reads as chapters, not as one endless page.
- One chapter is shown at a time; the nav is the table of contents. Pure
- CSS + a few lines of script, no fonts and nothing fetched, so it works
- offline inside the app exactly as it does in a browser. */
- main > section[data-chapter]:not([data-chapter-active]) { display: none; }
- .chapter-title {
- font-size: 12px;
- letter-spacing: .08em;
+ /* The walkthrough that opens every chapter. */
+ .walk {
+ background: var(--surface);
+ border: 1px solid var(--border);
+ border-left: 3px solid var(--accent);
+ border-radius: var(--radius);
+ padding: 1.25rem 1.4rem 1.4rem;
+ margin: 1.75rem 0;
+ }
+ .walk-head {
+ display: flex;
+ align-items: baseline;
+ gap: 0.6rem;
+ flex-wrap: wrap;
+ margin-bottom: 0.25rem;
+ }
+ .walk-head h3 { margin: 0; color: var(--text); font-size: 1.05rem; }
+ .walk-time {
+ font-size: 0.68rem;
+ font-weight: 700;
+ letter-spacing: 0.08em;
text-transform: uppercase;
- color: var(--text-dim, #8b8b8b);
- margin: 0 0 18px;
+ color: var(--accent);
+ background: var(--accent-glow);
+ border-radius: 99px;
+ padding: 0.1rem 0.6rem;
+ }
+ .walk-goal { font-size: 0.85rem; margin-bottom: 1rem; }
+ .walk ol { counter-reset: walkstep; list-style: none; margin: 0; padding: 0; }
+ .walk ol > li {
+ counter-increment: walkstep;
+ position: relative;
+ padding-left: 2.1rem;
+ margin-bottom: 1rem;
+ font-size: 0.875rem;
+ }
+ .walk ol > li::before {
+ content: counter(walkstep);
+ position: absolute;
+ left: 0;
+ top: 0.05rem;
+ width: 1.45rem;
+ height: 1.45rem;
+ border-radius: 50%;
+ background: var(--accent-glow);
+ border: 1px solid rgba(132, 204, 22, 0.35);
+ color: var(--accent);
+ font-size: 0.72rem;
+ font-weight: 700;
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ }
+ .walk .do { color: var(--text); display: block; }
+ .walk .say {
+ display: block;
+ background: #101013;
+ border: 1px solid var(--border);
+ border-left: 2px solid rgba(132, 204, 22, 0.4);
+ border-radius: 6px;
+ padding: 0.45rem 0.7rem;
+ margin: 0.4rem 0;
+ font-family: 'SF Mono', 'Fira Code', monospace;
+ font-size: 0.78rem;
+ color: #cfe89a;
+ white-space: pre-wrap;
+ }
+ .walk .then {
+ display: block;
+ font-size: 0.82rem;
+ color: var(--muted);
+ padding-left: 0.85rem;
+ border-left: 2px solid var(--border);
+ }
+ .walk .then::before {
+ content: 'You should see ';
+ color: var(--accent);
+ font-weight: 600;
+ }
+ .walk .stuck {
+ display: block;
+ font-size: 0.8rem;
+ color: #d8b46a;
+ margin-top: 0.3rem;
+ }
+ .walk .stuck::before { content: 'If not: '; font-weight: 600; }
+
+ /* Screenshot slot. Renders as a quiet placeholder until the file exists,
+ and swaps to the picture the moment it does - no build step, no 404 in
+ the middle of a paragraph. The precise shot instruction lives in an HTML
+ comment next to each figure and in REPORT-S10-DOCS.md, deliberately NOT
+ on screen: a reader must never be shown a production note. */
+ figure.shot { margin: 1.25rem 0; }
+ figure.shot img { display: block; width: 100%; border-radius: var(--radius); border: 1px solid var(--border); }
+ figure.shot figcaption { font-size: 0.78rem; color: var(--muted); margin-top: 0.45rem; }
+ figure.shot .slot { display: none; }
+ figure.shot.pending img { display: none; }
+ figure.shot.pending figcaption { display: none; }
+ figure.shot.pending .slot {
+ display: flex;
+ align-items: center;
+ gap: 0.6rem;
+ background: repeating-linear-gradient(45deg, #131316, #131316 10px, #17171b 10px, #17171b 20px);
+ border: 1px dashed var(--border);
+ border-radius: var(--radius);
+ padding: 1.1rem 1.25rem;
+ font-size: 0.8rem;
+ color: #6b6b74;
+ }
+ figure.shot.pending .slot b { color: var(--muted); font-weight: 600; }
+
+ /* "In this chapter" */
+ .lead-index { display: grid; grid-template-columns: repeat(auto-fill, minmax(230px, 1fr)); gap: 0.5rem; margin: 1.25rem 0 0; }
+ .lead-index a {
+ display: block;
+ background: var(--surface);
+ border: 1px solid var(--border);
+ border-radius: 0.5rem;
+ padding: 0.55rem 0.8rem;
+ text-decoration: none;
+ color: var(--text);
+ font-size: 0.83rem;
+ font-weight: 500;
+ transition: border-color 0.15s;
}
+ .lead-index a:hover { border-color: rgba(132, 204, 22, 0.4); color: var(--accent); }
+ .lead-index a span { display: block; font-weight: 400; font-size: 0.75rem; color: var(--muted); }
+
+ /* Chapters: one at a time. */
+ main > section[data-chapter]:not([data-chapter-active]) { display: none; }
.chapter-nav {
display: flex;
justify-content: space-between;
gap: 16px;
margin: 40px 0 8px;
padding-top: 20px;
- border-top: 1px solid var(--border, #2a2a2a);
+ border-top: 1px solid var(--border);
font-size: 14px;
}
.chapter-nav a { color: var(--accent); text-decoration: none; }
.chapter-nav a:hover { text-decoration: underline; }
- .chapter-nav span { color: var(--text-dim, #8b8b8b); }
+ .chapter-nav span { color: #6b6b74; }
+
+ /* Front page.
+ Stated the way round that survives having no script: with nothing
+ running, the body never gets .in-chapter, so the hero and the front page
+ stand and no section is hidden - the guide falls back to exactly the one
+ long page it used to be, rather than to a blank screen. */
+ body.in-chapter #frontpage { display: none; }
+ body.in-chapter .hero { display: none; }
+ body:not(.in-chapter) .chapter-nav { display: none; }
+ .front-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: 0.75rem; margin: 1.5rem 0; }
+ .front-card {
+ display: block;
+ background: var(--surface);
+ border: 1px solid var(--border);
+ border-radius: var(--radius);
+ padding: 1rem 1.1rem;
+ text-decoration: none;
+ transition: border-color 0.15s;
+ }
+ .front-card:hover { border-color: rgba(132, 204, 22, 0.4); }
+ .front-card .fc-num { font-family: monospace; font-size: 0.7rem; color: var(--accent); }
+ .front-card .fc-title { display: block; font-weight: 600; font-size: 0.95rem; color: var(--text); margin: 0.15rem 0 0.3rem; }
+ .front-card .fc-desc { display: block; font-size: 0.78rem; color: var(--muted); line-height: 1.5; }
+
+ .nav-toggle { display: none; }
+
+ @media (max-width: 900px) {
+ nav {
+ position: fixed;
+ z-index: 40;
+ left: 0; top: 0;
+ transform: translateX(-100%);
+ transition: transform 0.2s;
+ box-shadow: 0 0 40px rgba(0,0,0,0.6);
+ }
+ body.nav-open nav { transform: translateX(0); }
+ .nav-toggle {
+ display: block;
+ position: fixed;
+ z-index: 41;
+ top: 0.75rem; left: 0.75rem;
+ background: var(--surface);
+ border: 1px solid var(--border);
+ border-radius: 0.5rem;
+ color: var(--text);
+ font: inherit;
+ font-size: 0.8rem;
+ padding: 0.4rem 0.7rem;
+ cursor: pointer;
+ }
+ main { padding: 3.5rem 1.25rem 2rem; }
+ main section[id] { scroll-margin-top: 3.5rem; }
+ /* Wide content scrolls inside itself rather than widening the page. */
+ main table { display: block; width: 100%; overflow-x: auto; }
+ .os-grid { grid-template-columns: 1fr; }
+ .hero h1 { font-size: 1.9rem; }
+ .chapter-lead h2 { font-size: 1.6rem; }
+ }
</style>
</head>
<body>
+<button class="nav-toggle" aria-label="Show the table of contents">☰ Contents</button>
<div class="wrapper">
- <!-- Sidebar Nav -->
+ <!-- Sidebar: chapter switcher, search, and the table of contents -->
<nav>
- <a class="logo" href="#">
+ <a class="logo" href="#top">
<div class="logo-mark">S</div>
<div>
<div class="logo-text">Skales</div>
- <div class="logo-version">v<span data-skales-version>12.7.0</span> User Guide</div>
+ <div class="logo-version">v<span data-skales-version>12.7.2</span> User Guide</div>
</div>
</a>
+ <div class="search-box">
+ <input id="doc-search" type="search" placeholder="Search the guide" autocomplete="off" spellcheck="false" aria-label="Search the guide" />
+ <span class="search-key">/</span>
+ </div>
+
+ <div id="search-results"></div>
+
+ <div class="chapter-switch" id="chapter-switch">
+ <a href="#ch-start" data-chapter="start"><span class="num">1</span>Getting started</a>
+ <a href="#ch-chat" data-chapter="chat"><span class="num">2</span>Chat and agents</a>
+ <a href="#ch-code" data-chapter="code"><span class="num">3</span>Code</a>
+ <a href="#ch-studio" data-chapter="studio"><span class="num">4</span>Studio and Flow</a>
+ <a href="#ch-iris" data-chapter="iris"><span class="num">5</span>Iris and Voice</a>
+ <a href="#ch-auto" data-chapter="auto"><span class="num">6</span>Automation</a>
+ <a href="#ch-providers" data-chapter="providers"><span class="num">7</span>Providers and models</a>
+ <a href="#ch-mobile" data-chapter="mobile"><span class="num">8</span>Mobile and remote</a>
+ <a href="#ch-connected" data-chapter="connected"><span class="num">9</span>Connected life</a>
+ <a href="#ch-settings" data-chapter="settings"><span class="num">10</span>Settings and security</a>
+ <a href="#ch-help" data-chapter="help"><span class="num">11</span>Troubleshooting</a>
+ </div>
+
+ <div id="toc">
<div class="section-label" data-chapter="start">Getting started</div>
+ <a href="#ch-start" data-chapter="start">Overview and walkthrough</a>
<a href="#install" data-chapter="start">Installation</a>
<a href="#onboarding" data-chapter="start">First Launch</a>
<a href="#sidebar" data-chapter="start">Home and Work</a>
- <a href="#addons-view" data-chapter="start">Add-Ons and Settings views</a>
+ <a href="#addons-view" data-chapter="start">Add-Ons, and the two views of Settings</a>
- <div class="section-label" data-chapter="chat">Chat</div>
+ <div class="section-label" data-chapter="chat">Chat and agents</div>
+ <a href="#ch-chat" data-chapter="chat">Overview and walkthrough</a>
<a href="#chat" data-chapter="chat">Chat</a>
- <a href="#goal" data-chapter="chat">GOAL 🎯</a>
+ <a href="#shortcuts" data-chapter="chat">Chat Commands</a>
+ <a href="#goal" data-chapter="chat">GOAL</a>
+ <a href="#documents" data-chapter="chat">Document Generation</a>
+ <a href="#http-request" data-chapter="chat">Calling an API</a>
+ <a href="#easter-eggs" data-chapter="chat">Easter Eggs</a>
+ <div class="group-label" data-chapter="chat">What it remembers</div>
<a href="#memory" data-chapter="chat">Memory</a>
<a href="#memory-mode" data-chapter="chat">Memory Mode</a>
<a href="#knowledge-graph" data-chapter="chat">Knowledge Graph</a>
<a href="#vector-db" data-chapter="chat">External vector database</a>
- <a href="#group-chat" data-chapter="chat">Group Chat</a>
- <a href="#iris" data-chapter="chat">Iris Orbit 👁</a>
- <a href="#voice" data-chapter="chat">Live Voice</a>
- <a href="#own-speech" data-chapter="chat">Your own speech server</a>
<a href="#auto-compress" data-chapter="chat">Auto-Compress</a>
- <a href="#documents" data-chapter="chat">Document Generation</a>
- <a href="#easter-eggs" data-chapter="chat">Easter Eggs 🦎</a>
+ <div class="group-label" data-chapter="chat">Agents and teams</div>
+ <a href="#agents" data-chapter="chat">Agents</a>
+ <a href="#multi-agent" data-chapter="chat">Which multi-agent mode</a>
+ <a href="#group-chat" data-chapter="chat">Group Chat</a>
+ <a href="#organization" data-chapter="chat">Organization</a>
+ <a href="#swarm" data-chapter="chat">Agent Swarm</a>
+ <a href="#agent-sync" data-chapter="chat">Agent-to-Agent Protocol</a>
+ <div class="group-label" data-chapter="chat">Skills and tools</div>
+ <a href="#skills" data-chapter="chat">Skills</a>
+ <a href="#agent-skills" data-chapter="chat">Agent Skills Import</a>
+ <a href="#skills-interactive" data-chapter="chat">Custom Skill Interactive UI</a>
+ <a href="#skill-sharing" data-chapter="chat">Skill Sharing & Forking</a>
+ <a href="#mcp" data-chapter="chat">MCP Server Support</a>
<div class="section-label" data-chapter="code">Code</div>
- <a href="#code" data-chapter="code">Skales Code 💻</a>
+ <a href="#ch-code" data-chapter="code">Overview and walkthrough</a>
+ <a href="#code" data-chapter="code">Skales Code</a>
<a href="#chat-code-settings" data-chapter="code">Settings: Chat &amp; Code</a>
- <a href="#codework" data-chapter="code">Codework</a>
+ <a href="#codework" data-chapter="code">Skales Codework</a>
<a href="#playground" data-chapter="code">Playground</a>
<a href="#devkit" data-chapter="code">DevKit</a>
<a href="#github-int" data-chapter="code">GitHub</a>
<a href="#ftp" data-chapter="code">FTP/SFTP Deploy</a>
<div class="section-label" data-chapter="studio">Studio and Flow</div>
- <a href="#studio" data-chapter="studio">Studio</a>
+ <a href="#ch-studio" data-chapter="studio">Overview and walkthrough</a>
+ <a href="#studio" data-chapter="studio">Skales Studio</a>
<a href="#flow" data-chapter="studio">Flow</a>
- <a href="#images" data-chapter="studio">Image &amp; Video Gen</a>
+ <a href="#images" data-chapter="studio">Image & Video Generation</a>
<a href="#templates" data-chapter="studio">Templates</a>
<a href="#wordpress" data-chapter="studio">WordPress 2.0</a>
- <div class="section-label" data-chapter="agents">Agents and teams</div>
- <a href="#agents" data-chapter="agents">Agents</a>
- <a href="#multi-agent" data-chapter="agents">Which multi-agent mode</a>
- <a href="#skills" data-chapter="agents">Skills</a>
- <a href="#agent-skills" data-chapter="agents">Agent Skills Import</a>
- <a href="#skills-interactive" data-chapter="agents">Skill Interactive UI</a>
- <a href="#organization" data-chapter="agents">Organization</a>
- <a href="#swarm" data-chapter="agents">Agent Swarm</a>
- <a href="#agent-sync" data-chapter="agents">Agent-to-Agent</a>
- <a href="#skill-sharing" data-chapter="agents">Sharing Skills</a>
- <a href="#mcp" data-chapter="agents">MCP Servers</a>
+ <div class="section-label" data-chapter="iris">Iris and Voice</div>
+ <a href="#ch-iris" data-chapter="iris">Overview and walkthrough</a>
+ <a href="#iris" data-chapter="iris">Iris Orbit</a>
+ <a href="#voice" data-chapter="iris">Live Voice</a>
+ <a href="#own-speech" data-chapter="iris">Your own speech server</a>
+ <a href="#buddy" data-chapter="iris">Desktop Buddy</a>
+ <a href="#aipointer" data-chapter="iris">AIPointer ⦿</a>
<div class="section-label" data-chapter="auto">Automation</div>
+ <a href="#ch-auto" data-chapter="auto">Overview and walkthrough</a>
<a href="#ai-tasks" data-chapter="auto">Planner AI Tasks</a>
<a href="#planner" data-chapter="auto">Planner</a>
<a href="#autopilot" data-chapter="auto">Autopilot</a>
@@ -467,69 +826,217 @@
<a href="#browser" data-chapter="auto">Browser</a>
<a href="#computer-use" data-chapter="auto">Computer Use</a>
<a href="#download-file" data-chapter="auto">Download File</a>
- <a href="#http-request" data-chapter="auto">Calling an API</a>
-
- <div class="section-label" data-chapter="settings">Settings</div>
- <a href="#themes" data-chapter="settings">Themes</a>
- <a href="#accents" data-chapter="settings">Accent colours</a>
- <a href="#shortcuts" data-chapter="settings">Commands</a>
- <a href="#deep-links" data-chapter="settings">skales:// links</a>
- <a href="#notifications" data-chapter="settings">Notification Center</a>
- <a href="#dashboard" data-chapter="settings">Dashboard</a>
- <a href="#buddy" data-chapter="settings">Desktop Buddy</a>
- <a href="#export" data-chapter="settings">Export/Import Backup</a>
- <a href="#migration" data-chapter="settings">Migration Importer</a>
- <div class="section-label" data-chapter="security">Security</div>
- <a href="#safety" data-chapter="security">Safety Mode</a>
- <a href="#blocked-folders" data-chapter="security">Blocked folders</a>
- <a href="#danger-zone" data-chapter="security">Danger Zone</a>
- <a href="#tool-loop" data-chapter="security">Tool Loop Protection</a>
-
- <div class="section-label" data-chapter="providers">Providers</div>
+ <div class="section-label" data-chapter="providers">Providers and models</div>
+ <a href="#ch-providers" data-chapter="providers">Overview and walkthrough</a>
<a href="#providers" data-chapter="providers">Providers</a>
- <a href="#regional" data-chapter="providers">Which providers work where</a>
- <a href="#fallback" data-chapter="providers">Fallback Provider</a>
- <a href="#ollama-marketplace" data-chapter="providers">Ollama Marketplace</a>
+ <a href="#which-model" data-chapter="providers">Which model is answering</a>
+ <a href="#llm-profiles" data-chapter="providers">LLM Profiles</a>
+ <a href="#fallback" data-chapter="providers">Fallback Provider Chain</a>
+ <a href="#ollama-marketplace" data-chapter="providers">Ollama Model Marketplace</a>
<a href="#setup-koboldcpp" data-chapter="providers">KoboldCpp Setup</a>
<a href="#setup-lmstudio" data-chapter="providers">LM Studio Setup</a>
+ <div class="section-label" data-chapter="mobile">Mobile and remote</div>
+ <a href="#ch-mobile" data-chapter="mobile">Overview and walkthrough</a>
+ <a href="#mobile-app" data-chapter="mobile">Skales Mobile</a>
+ <a href="#pairing" data-chapter="mobile">Pairing a device</a>
+ <a href="#remote-access" data-chapter="mobile">Remote access</a>
+
<div class="section-label" data-chapter="connected">Connected life</div>
- <a href="#email" data-chapter="connected">Email</a>
- <a href="#calendar" data-chapter="connected">Calendar</a>
- <a href="#bots" data-chapter="connected">Bots</a>
- <a href="#twitter" data-chapter="connected">Twitter/X</a>
- <a href="#social" data-chapter="connected">Social Media</a>
- <a href="#notion" data-chapter="connected">Notion</a>
- <a href="#todoist" data-chapter="connected">Todoist</a>
- <a href="#spotify" data-chapter="connected">Spotify</a>
- <a href="#smarthome" data-chapter="connected">Smart Home</a>
+ <a href="#ch-connected" data-chapter="connected">Overview and walkthrough</a>
+ <a href="#email" data-chapter="connected">Email Integration</a>
+ <a href="#calendar" data-chapter="connected">Calendar Integration</a>
+ <a href="#bots" data-chapter="connected">Bot Integrations</a>
+ <a href="#twitter" data-chapter="connected">Twitter/X Integration</a>
+ <a href="#social" data-chapter="connected">Social Media Integration</a>
+ <div class="group-label" data-chapter="connected">Your accounts</div>
<a href="#google-account" data-chapter="connected">One Google account</a>
<a href="#gdrive" data-chapter="connected">Google Drive</a>
<a href="#gdocs" data-chapter="connected">Google Docs</a>
<a href="#places" data-chapter="connected">Google Places</a>
- <a href="#discover" data-chapter="connected">Discover Feed</a>
- <a href="#spark" data-chapter="connected">Spark ⚡</a>
+ <a href="#notion" data-chapter="connected">Notion</a>
+ <a href="#todoist" data-chapter="connected">Todoist</a>
+ <a href="#spotify" data-chapter="connected">Spotify</a>
+ <a href="#smarthome" data-chapter="connected">Smart Home</a>
+ <div class="group-label" data-chapter="connected">Out in the open</div>
+ <a href="#discover" data-chapter="connected">Discover — Social Network for AIs</a>
+ <a href="#spark" data-chapter="connected">Spark</a>
<a href="#wrapped" data-chapter="connected">Skales Wrapped</a>
- <a href="#aipointer" data-chapter="connected">AIPointer ⦿</a>
- <div class="section-label" data-chapter="help">Help</div>
- <a href="#long-runs" data-chapter="help">Long runs and sleep</a>
- <a href="#feedback" data-chapter="help">Feedback</a>
+ <div class="section-label" data-chapter="settings">Settings and security</div>
+ <a href="#ch-settings" data-chapter="settings">Overview and walkthrough</a>
+ <a href="#themes" data-chapter="settings">Themes</a>
+ <a href="#accents" data-chapter="settings">Your own accent colours</a>
+ <a href="#deep-links" data-chapter="settings">skales:// links</a>
+ <a href="#notifications" data-chapter="settings">Notification Center</a>
+ <a href="#dashboard" data-chapter="settings">Dashboard</a>
+ <div class="group-label" data-chapter="settings">Your data</div>
+ <a href="#updates" data-chapter="settings">Updates</a>
+ <a href="#export" data-chapter="settings">Export / Import Backup</a>
+ <a href="#migration" data-chapter="settings">Migration Importer</a>
+ <div class="group-label" data-chapter="settings">Security</div>
+ <a href="#safety" data-chapter="settings">Safety Mode</a>
+ <a href="#blocked-folders" data-chapter="settings">Folders Skales must never touch</a>
+ <a href="#tool-loop" data-chapter="settings">Tool Loop Protection</a>
+ <a href="#danger-zone" data-chapter="settings">Danger Zone</a>
+
+ <div class="section-label" data-chapter="help">Troubleshooting</div>
+ <a href="#ch-help" data-chapter="help">Overview and walkthrough</a>
+ <a href="#first-checks" data-chapter="help">When something will not work</a>
+ <a href="#long-runs" data-chapter="help">Long runs, sleep and the disk</a>
+ <a href="#feedback" data-chapter="help">Feedback & Reports</a>
+ </div>
</nav>
<!-- Main Content -->
<main>
- <!-- Hero -->
+ <!-- Hero: the front page only -->
<div class="hero">
- <div class="hero-badge">📖 Official Documentation · v<span data-skales-version>12.7.0</span></div>
+ <div class="hero-badge">📖 Official Documentation &middot; v<span data-skales-version>12.7.2</span></div>
<h1>Skales <span>User Guide</span></h1>
<p>Your personal AI operating system. Set a goal, automate, create, all running locally on your machine.</p>
</div>
- <!-- Installation -->
+ <div id="frontpage">
+ <p>Eleven chapters. Each one opens with a walkthrough you can follow on a real installation in about three minutes, and every chapter is one click away from every other one in the sidebar. If you know what you are looking for, the search at the top of the sidebar reaches every chapter at once - press <code>/</code> from anywhere.</p>
+ <div class="front-grid">
+ <a class="front-card" href="#ch-start">
+ <span class="fc-num">01</span>
+ <span class="fc-title">Getting started</span>
+ <span class="fc-desc">Install it, answer four questions, get a first answer out of it.</span>
+ </a>
+ <a class="front-card" href="#ch-chat">
+ <span class="fc-num">02</span>
+ <span class="fc-title">Chat and agents</span>
+ <span class="fc-desc">The conversation, what it remembers, the tools it can reach, and the agents and teams you build on top of it.</span>
+ </a>
+ <a class="front-card" href="#ch-code">
+ <span class="fc-num">03</span>
+ <span class="fc-title">Code</span>
+ <span class="fc-desc">A window of its own for working on a repository, with a leash you choose per session.</span>
+ </a>
+ <a class="front-card" href="#ch-studio">
+ <span class="fc-num">04</span>
+ <span class="fc-title">Studio and Flow</span>
+ <span class="fc-desc">Pictures, video, voice, music, and the conversational design workspace that keeps working on a brief with you.</span>
+ </a>
+ <a class="front-card" href="#ch-iris">
+ <span class="fc-num">05</span>
+ <span class="fc-title">Iris and Voice</span>
+ <span class="fc-desc">Talking to Skales instead of typing at it, and the two assistants that live on your screen.</span>
+ </a>
+ <a class="front-card" href="#ch-auto">
+ <span class="fc-num">06</span>
+ <span class="fc-title">Automation</span>
+ <span class="fc-desc">Work that happens on a schedule, in the background, or on a website instead of in a chat.</span>
+ </a>
+ <a class="front-card" href="#ch-providers">
+ <span class="fc-num">07</span>
+ <span class="fc-title">Providers and models</span>
+ <span class="fc-desc">Where the answers come from, how to know which model is answering, and how to run one on your own machine.</span>
+ </a>
+ <a class="front-card" href="#ch-mobile">
+ <span class="fc-num">08</span>
+ <span class="fc-title">Mobile and remote</span>
+ <span class="fc-desc">Your phone as a second window onto the Skales running at home, and the two ways it gets there.</span>
+ </a>
+ <a class="front-card" href="#ch-connected">
+ <span class="fc-num">09</span>
+ <span class="fc-title">Connected life</span>
+ <span class="fc-desc">Mail, calendar, messengers, the accounts you already have, and the feed Skales publishes to.</span>
+ </a>
+ <a class="front-card" href="#ch-settings">
+ <span class="fc-num">10</span>
+ <span class="fc-title">Settings and security</span>
+ <span class="fc-desc">Making it look like yours, keeping it up to date, and deciding what it is allowed to do.</span>
+ </a>
+ <a class="front-card" href="#ch-help">
+ <span class="fc-num">11</span>
+ <span class="fc-title">Troubleshooting</span>
+ <span class="fc-desc">The five checks that answer most of it, and where to send what they do not.</span>
+ </a>
+ </div>
+ <div class="tip"><strong>New here?</strong> Chapter 1 takes you from a downloaded file to two answers on screen. <strong>Something not working?</strong> Chapter 11 has the five checks that answer most of it.</div>
+ </div>
+
+ <!-- ===== Chapter: Getting started ===== -->
+ <section id="ch-start" class="chapter-lead">
+ <div class="lead-kicker">Chapter 1</div>
+ <h2>Getting started</h2>
+ <p class="lead-intro">Skales runs on your computer. There is no account to make and nothing to sign up for, and the whole of this chapter is the distance between a downloaded file and an answer on screen.</p>
+
+ <div class="walk">
+ <div class="walk-head"><h3>Walkthrough: from installer to first answer</h3><span class="walk-time">3 minutes</span></div>
+ <p class="walk-goal">At the end of this you will have Skales running, one provider configured, and two answers on screen: one plain, one that used a tool.</p>
+ <ol>
+ <li>
+ <span class="do">Download the build for your system from <strong>skales.app</strong> and open it. On macOS, right-click the app and choose <strong>Open</strong> the first time.</span>
+ <span class="then">the setup screen, starting with the language list.</span>
+ </li>
+ <li>
+ <span class="do">Pick your language, then a provider. If you have no API key at all, pick <strong>Skales IQ</strong>: it needs no key and it includes tools and vision.</span>
+ <span class="then">the model list filling itself in under the provider.</span>
+ <span class="stuck">the list stays empty, the key was refused. Check it against the provider's own site from the same connection before changing anything in Skales, and read <a href="#regional">Which providers work where</a>.</span>
+ </li>
+ <li>
+ <span class="do">Answer <strong>What should Skales do for you</strong>. Pick the one that is closest; you are choosing which add-ons start switched on, not a mode you are locked into.</span>
+ <span class="then">a sidebar built from that answer rather than a sidebar with thirty entries in it.</span>
+ </li>
+ <li>
+ <span class="do">You land in Chat. Ask it something plain:</span>
+ <span class="say">Summarise in five bullet points what you can do for me on this computer.</span>
+ <span class="then">the answer streaming in, and under the composer a line naming the model that is answering and how much of its context window the conversation is using.</span>
+ </li>
+ <li>
+ <span class="do">Now ask for something it has to go and get, so you see a tool run:</span>
+ <span class="say">Search the web for the three most recent reviews of Skales and give me the links.</span>
+ <span class="then">a search step appear inline above the answer, which you can open to see exactly what was asked and what came back.</span>
+ <span class="stuck">nothing happens, web search is one of the nine things that are always on, so it is a provider problem rather than a setting. The <a href="#first-checks">first five checks</a> are the fastest way through it.</span>
+ </li>
+ </ol>
+ </div>
+
+ <!-- SHOT start-onboarding-work.png
+ Onboarding, the "What should Skales do for you" step (step 5 of 5).
+ Frame: whole app window, 1440x900, dark theme, default accent.
+ Must show: the five kinds of work as cards, one of them selected, and the
+ individual add-on switches underneath it on the same screen.
+ Do NOT show: any API key, even partially.
+ -->
+ <figure class="shot pending">
+ <img src="img/start-onboarding-work.png" alt="The last setup question decides what the sidebar shows." loading="lazy" />
+ <div class="slot"><b>Screenshot</b> &middot; The last setup question decides what the sidebar shows.</div>
+ <figcaption>The last setup question decides what the sidebar shows.</figcaption>
+ </figure>
+
+ <!-- SHOT start-first-answer.png
+ Chat, immediately after the answer to "Summarise in five bullet points...".
+ Frame: whole app window, 1440x900, dark theme, sidebar visible.
+ Must show: the composer, the readout line under it naming the model and the
+ context use, the status pill, and one short finished answer above.
+ The model named in the readout must be the model that actually answered -
+ this shot doubles as the picture of the 12.7.1 fix.
+ -->
+ <figure class="shot pending">
+ <img src="img/start-first-answer.png" alt="A first answer, with the model readout under the composer." loading="lazy" />
+ <div class="slot"><b>Screenshot</b> &middot; A first answer, with the model readout under the composer.</div>
+ <figcaption>A first answer, with the model readout under the composer.</figcaption>
+ </figure>
+
+ <p>What follows in this chapter: what happens on first launch, how the sidebar is put together, and the two controls that decide how much of Skales you have to look at.</p>
+
+ <h3>In this chapter</h3>
+ <div class="lead-index">
+ <a href="#install">Installation</a>
+ <a href="#onboarding">First Launch</a>
+ <a href="#sidebar">Home and Work</a>
+ <a href="#addons-view">Add-Ons, and the two views of Settings</a>
+ </div>
+ </section>
+
<section id="install">
<h2><span class="icon">💾</span> Installation</h2>
<p>Download Skales from <strong>skales.app</strong>. Choose the build for your operating system.</p>
@@ -537,7 +1044,7 @@
<div class="os-grid">
<div class="os-card">
<div class="os-name">🍎 macOS</div>
- <p>Code-signed with Apple Developer ID. If Gatekeeper shows a warning, right-click the app → <strong>Open</strong>. Notarization is coming in a future release.</p>
+ <p>Code-signed with an Apple Developer ID and notarized by Apple, so it opens by double-clicking like any other app. An older download that predates notarization still needs right-click → <strong>Open</strong> the first time.</p>
</div>
<div class="os-card">
<div class="os-name">🪟 Windows</div>
@@ -556,7 +1063,6 @@
</div>
</section>
- <!-- Onboarding -->
<section id="onboarding">
<h2><span class="icon">🚀</span> First Launch</h2>
<p>The <strong>onboarding wizard</strong> guides you through setup on first launch:</p>
@@ -580,159 +1086,135 @@
<p style="color: var(--muted); font-size: 0.875rem;">You can review or revoke any of these later in your system settings, and Skales keeps working without the ones you skip.</p>
</section>
- <!-- Providers -->
- <section id="providers">
- <h2><span class="icon">🔌</span> Providers</h2>
- <p>Skales supports multiple AI providers. Configure them in <strong>Settings → Providers</strong>.</p>
- <p>Skales works with any model you configure, and it tells you which model it is running. The active model is shown below the composer and in the system tray, so you always know what is answering.</p>
+ <section id="sidebar">
+ <h2><span class="icon">🗂️</span> Home and Work</h2>
+ <p>The sidebar has a personal side and a working side, and the switch at the top decides which one you are looking at. The point is that a sidebar with thirty entries is a sidebar nobody reads.</p>
+ <p>What the switch actually swaps is the <strong>Main</strong> group and the third group under it. Everything else stands in both.</p>
+ <ul style="margin: 0.75rem 0 1rem 1.5rem; color: var(--muted); font-size: 0.875rem;">
+ <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Main, on both sides.</strong> Dashboard, Chat, History, Discover, Memory. Somebody working has the same two questions as somebody at home — talk to it, and find what was said — so having to leave Work to ask them would make the switch a toll rather than a view.</li>
+ <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Main, Home only.</strong> Lio AI.</li>
+ <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Main, Work only.</strong> Code, Organization, Autopilot, Teams. Code and Teams stand there whatever the Add-Ons page says, because a Work side that can end up identical to Home is a switch that earns nothing.</li>
+ <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Workspace, on both sides.</strong> Iris Orbit, Studio, Agents, Tasks, Schedule, Planner, Projects.</li>
+ <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Personal (Home) / Build (Work).</strong> Home shows Browser, Group Chat, Spaces, Wrapped. Work shows Codework, Browser, Playbooks, Workflow, WordPress, Swarm.</li>
+ <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Custom Widgets and System, on both sides.</strong> Skales Mobile, Add-Ons, Custom Skills, Custom Widgets, Templates, Logs, Update.</li>
+ </ul>
+ <p>An entry whose add-on is switched off is simply not in the list. Nothing is lost either way: the side you were on is remembered, and the page you are actually on is always visible in the sidebar, so a link or a finished task can never land you somewhere the menu does not show.</p>
+ </section>
- <h3>The provider grid</h3>
- <p>The page opens with a grid: one tile per provider, with a short description, badges for what it can do beyond chat (Voice, Vision, Generative, Local), and a switch. The filter chips above the grid narrow it to one of those capabilities.</p>
+ <section id="addons-view">
+ <h2><span class="icon">🧩</span> Add-Ons, and the two views of Settings</h2>
+ <p>Skales can do a great many things, and nobody uses all of them. Two controls decide how much of that you have to look at, and neither of them turns anything off that you switched on.</p>
+
+ <h3>The Add-Ons page</h3>
+ <p><strong>Sidebar → System → Add-Ons.</strong> One card per add-on, one switch each. An add-on that has a page of its own puts that page in the sidebar while it is on and takes it away again when it is off; an add-on that needs an account says which key it needs and where to put it.</p>
+ <p>Nine things are not on the list because they are not a choice: weather, summarizing, documents, web search, the system monitor, local file chat, screenshots and vision, VirusTotal and Wrapped. Switching those off would make Skales worse at being Skales, and nobody came to a setup screen to decide them.</p>
+ <p>The five categories in the setup screen are a shortcut into the same switches, not a mode. Picking <em>Coding AI</em> preselects that bundle; what gets stored is the add-ons, not the category.</p>
+
+ <h3>Standard and Advanced</h3>
+ <p>The switch at the top of <strong>Settings</strong> chooses between two views of the same page.</p>
<ul style="margin: 0.75rem 0 1rem 1.5rem; color: var(--muted); font-size: 0.875rem;">
- <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Switch on</strong> to get the provider's full card below the grid, where the key, the model and the rest live.</li>
- <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Switch off</strong> to put the card away. This is not deleting: the key stays saved and comes straight back when you switch the provider on again. A provider that is off also stops appearing in the model pickers, which is the point of the switch.</li>
- <li style="margin-bottom: 0.5rem;">The provider you have set <strong style="color:var(--text)">Active</strong> cannot be switched off &mdash; make another one active first. If anything else still points at a provider (agents, the fallback chain, per-mode overrides, Lio), the tile says so before you switch it off.</li>
- <li style="margin-bottom: 0.5rem;">A fresh install shows Skales IQ and Ollama. An existing one opens on exactly the providers it was already using, and whatever you set up in onboarding is switched on for you.</li>
- <li style="margin-bottom: 0.5rem;">Searching Settings reaches providers that are switched off too &mdash; their tile shows &ldquo;Switch on to configure&rdquo; rather than hiding.</li>
- <li style="margin-bottom: 0.5rem;">The grid has a <strong style="color:var(--text)">chevron header</strong> that folds it away, and the fold is remembered across restarts. If you come here for one provider every day, fold the grid once and its card is at the top from then on. The header keeps showing how many providers are switched on, and a search opens the grid again so a match is never hidden behind the fold.</li>
+ <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Standard</strong> shows the settings your add-ons actually need, plus the ones everybody needs. A section that belongs to an add-on you have not switched on is not there.</li>
+ <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Advanced</strong> shows every setting there is, exactly as before.</li>
</ul>
- <p><strong>+ Custom endpoint</strong> is a tile in the same grid: it opens the extra OpenAI-compatible endpoints (LM Studio, llama.cpp, vLLM, koboldcpp, a second local server) right under the cards. The same door sits inside the Custom endpoint card itself, as <strong>+ Add another endpoint</strong>, so you do not have to scroll back up to the grid to add a second one. Each extra endpoint has its own <strong>Set Active</strong> button, so any of them can be the provider Skales routes to by default, not only one you pick per chat.</p>
- <p>A model you type into a provider card yourself &mdash; which is the only kind the Custom endpoint has &mdash; is searchable in the chat model picker like any other. You do not have to make the provider active first to reach its model.</p>
- <p>Each card carries its own <strong>Timeout, retries and model limits</strong> block, folded shut until you need it. Fallback chain, advisor strategy, per-mode overrides and the global request timeout live together in one collapsed <strong>Advanced Routing</strong> section at the bottom of the page. The ChatGPT (Codex) subscription sits inside the OpenAI card, since that is the account it belongs to.</p>
+ <p>It is a <em>view</em>, not a state. Anything you switched on in Advanced stays on in Standard — it is only out of sight. Search reaches both views, so typing what you are looking for finds it whichever one you are in, and a tab that would open onto an empty page in Standard is not offered.</p>
+ <p>The Advanced view is not a list of dangerous things. Diagnostics, Updates, Export/Import and the data controls all sit in the <strong>Advanced tab</strong> and are all shown in the Standard view, because those are things ordinary users are sent to.</p>
- <div class="provider-list">
- <div class="provider-item">
- <div class="provider-dot"></div>
- <div class="provider-name">Skales IQ</div>
- <div class="provider-desc">Free trial, no API key needed. A capable model runs on our servers, with tools and vision included. Activate it in onboarding or in Settings &rarr; AI Providers. When the trial runs out, add your own key and keep going for free, or switch to a local model.</div>
- <div class="provider-rec">Free</div>
- </div>
- <div class="provider-item">
- <div class="provider-dot"></div>
- <div class="provider-name">OpenRouter</div>
- <div class="provider-desc">Gateway to 200+ models from all major labs. One API key, maximum flexibility.</div>
- <div class="provider-rec">Recommended</div>
- </div>
- <div class="provider-item">
- <div class="provider-dot"></div>
- <div class="provider-name">Anthropic</div>
- <div class="provider-desc">Direct Claude access (Haiku, Sonnet, Opus). Best for coding and analysis.</div>
- </div>
- <div class="provider-item">
- <div class="provider-dot"></div>
- <div class="provider-name">Google</div>
- <div class="provider-desc">Gemini 2.0 Flash and Pro. Strong at multimodal tasks and long context.</div>
- </div>
- <div class="provider-item">
- <div class="provider-dot"></div>
- <div class="provider-name">Groq</div>
- <div class="provider-desc">Blazing-fast inference on Llama and Mixtral models. Great for real-time tasks.</div>
- </div>
- <div class="provider-item">
- <div class="provider-dot muted"></div>
- <div class="provider-name">Ollama</div>
- <div class="provider-desc">Fully local models. Complete privacy — no data leaves your machine. Requires Ollama installed.</div>
- </div>
- <div class="provider-item">
- <div class="provider-dot muted"></div>
- <div class="provider-name">OpenAI</div>
- <div class="provider-desc">GPT-4o, GPT-4 Turbo, o1 series. Direct OpenAI integration.</div>
- </div>
- <div class="provider-item">
- <div class="provider-dot muted"></div>
- <div class="provider-name">Mistral</div>
- <div class="provider-desc">Mistral AI, Mixtral, and Codestral models. Fast, efficient models for general and code tasks.</div>
- </div>
- <div class="provider-item">
- <div class="provider-dot muted"></div>
- <div class="provider-name">Together AI</div>
- <div class="provider-desc">Access open-source models like Llama, Mistral, and fine-tuned variants via Together's platform.</div>
- </div>
- <div class="provider-item">
- <div class="provider-dot muted"></div>
- <div class="provider-name">xAI</div>
- <div class="provider-desc">Grok models from xAI. Real-time reasoning on current information.</div>
- </div>
- <div class="provider-item">
- <div class="provider-dot muted"></div>
- <div class="provider-name">DeepSeek</div>
- <div class="provider-desc">DeepSeek API with R1 and other advanced reasoning models.</div>
- </div>
- <div class="provider-item">
- <div class="provider-dot muted"></div>
- <div class="provider-name">Minimax</div>
- <div class="provider-desc">MiniMax API for accessing advanced language models.</div>
- </div>
- <div class="provider-item">
- <div class="provider-dot muted"></div>
- <div class="provider-name">Nvidia NIM</div>
- <div class="provider-desc">Nemotron 3 Super and Ultra, GLM 5.2, DeepSeek V4 Pro and Flash, GPT-OSS 120B, Qwen3 Next 80B, Llama 3.3 70B, on Nvidia GPUs. Every model in that list was verified by making a real call rather than by reading the catalogue &mdash; which lists many more that no longer answer. The largest can take over a minute before the first word arrives; that is the model warming up, not a hang.</div>
- </div>
- <div class="provider-item">
- <div class="provider-dot muted"></div>
- <div class="provider-name">Moonshot (Kimi)</div>
- <div class="provider-desc">Kimi K3 and the K2 line. Long context, strong agentic tool use. Two separate services with separate accounts; the region is a switch on the provider card.</div>
- </div>
- <div class="provider-item">
- <div class="provider-dot muted"></div>
- <div class="provider-name">GLM (z.ai)</div>
- <div class="provider-desc">Zhipu GLM 5.2 and 4.6. Strong coding and agentic tool use, long context.</div>
- </div>
- <div class="provider-item">
- <div class="provider-dot muted"></div>
- <div class="provider-name">Qwen (DashScope)</div>
- <div class="provider-desc">Alibaba Qwen3 Max, Coder and Turbo. Broad multilingual coverage, very long context.</div>
- </div>
- <div class="provider-item">
- <div class="provider-dot muted"></div>
- <div class="provider-name">Hunyuan (Tencent)</div>
- <div class="provider-desc">Tencent Hy3: 256K context, fast and slow thinking in one model, strong at agents and code. Three separate services with separate accounts &mdash; TokenHub Singapore, TokenHub China, and the older Hunyuan API, which serves the hunyuan-* models instead of Hy3. The endpoint is a switch on the provider card.</div>
- </div>
- <div class="provider-item">
- <div class="provider-dot muted"></div>
- <div class="provider-name">Replicate</div>
- <div class="provider-desc">Bring Your Own Key (BYOK) for Replicate. Run open-source models on their infrastructure.</div>
- </div>
- <div class="provider-item">
- <div class="provider-dot muted"></div>
- <div class="provider-name">Cerebras</div>
- <div class="provider-desc">Ultra-fast inference on Llama models. Dedicated wafer-scale hardware.</div>
- </div>
- <div class="provider-item">
- <div class="provider-dot muted"></div>
- <div class="provider-name">Perplexity</div>
- <div class="provider-desc">Search-augmented AI models. Real-time web knowledge built in.</div>
- </div>
- <div class="provider-item">
- <div class="provider-dot muted"></div>
- <div class="provider-name">Custom Endpoint</div>
- <div class="provider-desc">Connect any OpenAI-compatible API — LM Studio, KoboldCpp, vLLM, or any local server.</div>
- </div>
- </div>
-
- <div class="tip"><strong>💡 Local AI Setup:</strong> Need help setting up local models? See our step-by-step guides: <a href="setup-koboldcpp.html" style="color:var(--accent)">KoboldCpp Setup</a> · <a href="setup-lmstudio.html" style="color:var(--accent)">LM Studio Setup</a></div>
-
- <div class="tip"><strong>💡 Tip:</strong> You can configure multiple providers and switch between them mid-session. Use <code>/model gpt-4o</code> or the model picker in the chat toolbar.</div>
-
- <div class="tip"><strong>Ollama, keeping models loaded:</strong> The Ollama card has a <strong>Keep models loaded</strong> setting - how long the daemon holds a model in VRAM after a turn. Longer means the next turn starts warm; shorter means the card frees up sooner. It matters most for a squad: several agents on several local models pin all of them for that whole window, which is how a 24 GB card ends up swapping to system RAM. Pick <em>Unload immediately</em> if VRAM is tight, <em>Keep loaded</em> if you have room and want no cold starts. The change applies to the very next turn - no restart. <code>SKALES_OLLAMA_KEEP_ALIVE</code> still overrides it for scripted installs.</div>
-
- <div class="tip"><strong>🔄 Live model fetch (v10.2.2):</strong> Each provider card has a Refresh button that pulls the current model list directly from the provider's API. The cached list is preferred over the built-in baseline, so newly released models become usable without waiting for a Skales release. Supported providers: Anthropic, OpenAI, Google Gemini, Groq, DeepSeek, Mistral, xAI, Together, MiniMax, Cloudflare, NVIDIA, SambaNova, Cerebras (plus the existing OpenRouter, Ollama, and Custom Endpoint flows).</div>
+ <h3>Changing your mind</h3>
+ <p><strong>Settings → Advanced → Setup</strong> runs the add-on screen again. Nothing is deleted by it: chats, keys and settings stay exactly as they are, and only what is shown changes.</p>
+ </section>
- <div class="tip"><strong>⚙️ Override Model Limits (power user):</strong> Settings → AI Providers → the provider's card → <em>Timeout, retries and model limits</em>. Add per-(provider, model) override rows for context and output token caps. Use <code>*</code> as the model name for a provider-wide wildcard. Useful when a brand-new model has different limits than the built-in registry — no Skales update required.</div>
+ <!-- ===== Chapter: Chat and agents ===== -->
+ <section id="ch-chat" class="chapter-lead">
+ <div class="lead-kicker">Chapter 2</div>
+ <h2>Chat and agents</h2>
+ <p class="lead-intro">Chat is the whole product with a text box in front of it. The same engine answers a question, runs a ten-step goal, keeps what it learned about you, and fans work out to a team, so this chapter starts at one message and ends at several agents working at once.</p>
+
+ <div class="walk">
+ <div class="walk-head"><h3>Walkthrough: a question, a tool, a goal, an agent</h3><span class="walk-time">3 minutes</span></div>
+ <p class="walk-goal">Four messages, each one a different gear of the same engine.</p>
+ <ol>
+ <li>
+ <span class="do">Ask something it can answer from what it knows:</span>
+ <span class="say">Explain the difference between a goal and a task in Skales, in four sentences.</span>
+ <span class="then">a plain answer with no tool steps above it.</span>
+ </li>
+ <li>
+ <span class="do">Drag a screenshot onto the composer and ask about it:</span>
+ <span class="say">What is wrong with the layout in this screenshot?</span>
+ <span class="then">the image as an attachment on your message, and an answer that describes what is actually in it.</span>
+ <span class="stuck">the answer talks about an image it cannot see, the model you are on has no vision. The provider grid marks the ones that do with a <strong>Vision</strong> badge.</span>
+ </li>
+ <li>
+ <span class="do">Hand it something big enough to need a plan:</span>
+ <span class="say">/goal Find three articles published this month about local AI assistants, and write me a one page summary with the sources at the bottom.</span>
+ <span class="then">Skales restate the goal, lay out a plan, and then work through it on its own. It stops only when it is done, when it needs a decision, or before something consequential like sending mail.</span>
+ </li>
+ <li>
+ <span class="do">Open the persona picker at the top of the chat and switch to a different agent, then ask the same question again.</span>
+ <span class="then">a different answer and a different session history, because an agent carries its own system prompt and its own thread.</span>
+ </li>
+ <li>
+ <span class="do">Ask for several deliverables at once, which is the point where one chat becomes a team:</span>
+ <span class="say">Write five short competitor summaries, one each for the five best known note taking apps.</span>
+ <span class="then">five background agents in the Tasks tab, each reporting its result back into this thread as it finishes.</span>
+ </li>
+ </ol>
+ </div>
- <h3 id="regional">Which providers work where</h3>
- <p>Skales runs on your machine and talks to whichever provider you configure, so what is reachable from your country is decided by that provider, not by Skales. This matters most for the recommended default: <strong>OpenRouter does not serve every country</strong>, and where it does not, its key will not work no matter how it is entered. Nothing about Skales itself is limited by where you are.</p>
- <p>If OpenRouter is not available to you, every one of these is a full replacement &mdash; they are ordinary providers in the same grid, with the same tools, vision and agent features:</p>
- <ul style="margin: 0.75rem 0 1rem 1.5rem; color: var(--muted); font-size: 0.875rem;">
- <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">DeepSeek</strong>, direct rather than through a gateway. Own account, own key, reasoning models included.</li>
- <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Moonshot (Kimi)</strong>, <strong style="color:var(--text)">GLM (z.ai)</strong>, <strong style="color:var(--text)">Qwen (DashScope)</strong> and <strong style="color:var(--text)">Hunyuan (Tencent)</strong>. All four are first-class provider cards. Moonshot and Hunyuan each serve several regions from separate accounts, and the region is a switch on the card &mdash; pick the one your account belongs to.</li>
- <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Custom endpoint</strong>, for any OpenAI-compatible service that answers where you are, including one you host yourself. Add as many as you need.</li>
- <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Ollama</strong>, fully local. Nothing leaves the machine, so there is no country question at all. This is the option that always works.</li>
- </ul>
- <p>If a key is rejected and you are unsure whether it is the key or the location, try the same key against the provider's own site from the same connection. If it fails there too, the answer is the connection, and one of the alternatives above is the way forward.</p>
+ <!-- SHOT chat-goal-running.png
+ Chat with a /goal run in progress, several steps done and one still working.
+ Frame: whole app window, 1440x900, dark theme.
+ Must show: the restated goal and plan at the top of the run, at least two
+ completed tool steps (collapsed is fine), and the goal indicator in the chat
+ header. Ideally one Continuation Card visible.
+ -->
+ <figure class="shot pending">
+ <img src="img/chat-goal-running.png" alt="A goal in flight: the plan, the steps, and the header that says it is running." loading="lazy" />
+ <div class="slot"><b>Screenshot</b> &middot; A goal in flight: the plan, the steps, and the header that says it is running.</div>
+ <figcaption>A goal in flight: the plan, the steps, and the header that says it is running.</figcaption>
+ </figure>
+
+ <!-- SHOT chat-tool-step-open.png
+ Chat, one tool step expanded (a web search is the clearest).
+ Frame: the message area only, cropped to about 900px wide.
+ Must show: the query that was sent, the result that came back, and the copy
+ button. This is the picture for "tool results are shown inline".
+ -->
+ <figure class="shot pending">
+ <img src="img/chat-tool-step-open.png" alt="Any step opens: what was sent, and everything that came back." loading="lazy" />
+ <div class="slot"><b>Screenshot</b> &middot; Any step opens: what was sent, and everything that came back.</div>
+ <figcaption>Any step opens: what was sent, and everything that came back.</figcaption>
+ </figure>
+
+ <p>Read <a href="#chat">Chat</a> and <a href="#goal">GOAL</a> first. <a href="#multi-agent">Which multi-agent mode</a> is worth reading before you build a team, because Skales has three of them and they are for three different things.</p>
+
+ <h3>In this chapter</h3>
+ <div class="lead-index">
+ <a href="#chat">Chat</a>
+ <a href="#shortcuts">Chat Commands</a>
+ <a href="#goal">GOAL</a>
+ <a href="#documents">Document Generation</a>
+ <a href="#http-request">Calling an API</a>
+ <a href="#easter-eggs">Easter Eggs</a>
+ <a href="#memory">Memory<span>What it remembers</span></a>
+ <a href="#memory-mode">Memory Mode<span>What it remembers</span></a>
+ <a href="#knowledge-graph">Knowledge Graph<span>What it remembers</span></a>
+ <a href="#vector-db">External vector database<span>What it remembers</span></a>
+ <a href="#auto-compress">Auto-Compress<span>What it remembers</span></a>
+ <a href="#agents">Agents<span>Agents and teams</span></a>
+ <a href="#multi-agent">Which multi-agent mode<span>Agents and teams</span></a>
+ <a href="#group-chat">Group Chat<span>Agents and teams</span></a>
+ <a href="#organization">Organization<span>Agents and teams</span></a>
+ <a href="#swarm">Agent Swarm<span>Agents and teams</span></a>
+ <a href="#agent-sync">Agent-to-Agent Protocol<span>Agents and teams</span></a>
+ <a href="#skills">Skills<span>Skills and tools</span></a>
+ <a href="#agent-skills">Agent Skills Import<span>Skills and tools</span></a>
+ <a href="#skills-interactive">Custom Skill Interactive UI<span>Skills and tools</span></a>
+ <a href="#skill-sharing">Skill Sharing & Forking<span>Skills and tools</span></a>
+ <a href="#mcp">MCP Server Support<span>Skills and tools</span></a>
+ </div>
</section>
- <!-- Chat -->
<section id="chat">
<h2><span class="icon">💬</span> Chat</h2>
<p>The main conversation interface. Skales remembers context, executes tools, and builds session history.</p>
@@ -754,128 +1236,20 @@
</div>
</section>
- <!-- CODE MODE (v11.2.1) -->
- <section id="code">
- <h2><span class="icon">💻</span> Skales Code</h2>
- <p>Skales Code is a window of its own, built for working on a repository. Click <strong>Code</strong> in the sidebar and it opens beside Skales rather than inside it, so you can keep chatting and using everything else while it works. Point it at a folder and say what you want changed.</p>
-
- <h3>Starting a session</h3>
- <p>Three ways in: <strong>Open project</strong> picks a folder on this computer, <strong>Clone repo</strong> takes an address (an ssh address included) and clones it into your workspace, and the sessions you had open before are listed underneath with their branch and the size of the change in each. The status line along the bottom always says what is going on: idle or working, which folder, which branch, and how many lines have been added and removed.</p>
-
- <h3>The four modes, and what each may do</h3>
- <p>You pick the leash when the session starts, in the box you type into. It is the session that decides, not your global Safety Mode: set the rest of Skales to Unrestricted and a session set to <strong>Code</strong> still asks, because that is what choosing Code meant.</p>
- <ul>
- <li><strong>Ask</strong> &mdash; reads and answers. It cannot change anything: the tools that write are refused, not merely discouraged.</li>
- <li><strong>Plan</strong> &mdash; the same, and the output is a plan. Carrying it out is a separate decision.</li>
- <li><strong>Code</strong> &mdash; writes, and asks before every file change and every command, once each, with an &ldquo;always allow&rdquo; for the ones that get tiring.</li>
- <li><strong>Accept edits</strong> &mdash; file changes go through without asking, because choosing this mode <em>is</em> that consent. Commands, pushes and deploys still ask.</li>
- <li><strong>Auto</strong> &mdash; gets on with it. It still asks about anything that reaches <em>outside</em> the bound folder, anything catastrophic, and anything the scope check flags as more than you asked for.</li>
- </ul>
- <div class="warn">
- <strong>🔒 What no mode lifts</strong> &mdash; Blocked folders stay blocked, every path resolves inside the bound folder, catastrophic commands are refused rather than offered, and a coding session never reads or writes your memory. Auto does not switch any of that off.
- </div>
-
- <h3>Reading a session</h3>
- <p>Every step opens. Click a Read, a Grep, an Edit or a command and it unfolds: exactly what was sent and everything that came back, whole, scrollable, with a copy button on each half, and how long the step took. A change carries its diff on the step that made it, with its own added and removed counts and its own <strong>Keep</strong> and <strong>Revert</strong>. Every path is a link into the panel beside the transcript.</p>
-
- <h3>Review, commit, pull request</h3>
- <p><strong>Review diff</strong> opens the panel with every file the session touched. Keep stages a change for the next commit, Put back restores the file and tells you where the old version came from. Commit from the same panel, push, and open a pull request without leaving the window. When git refuses, you get git&rsquo;s own words back.</p>
-
- <h3>The artefact panel and the picker</h3>
- <p>The panel beside the transcript shows a file three ways: <strong>Preview</strong>, <strong>Diff</strong> and <strong>Raw</strong>. An HTML file is not shown as source but <em>run</em>, with its own stylesheet and script, so a widget works there the way it will work anywhere. Turn on the picker and click an element in that running page: what to call it in CSS, its own markup and a picture of just that piece go onto the message you are writing.</p>
-
- <h3>Two things at once: worktrees</h3>
- <p>Give a second piece of work a name and Skales checks the repository out again into a folder of its own, on a branch of its own, with its own session. Neither run can overwrite the other, and each session says whether it is working, waiting for you, or idle. Removing a parallel checkout tells you when there is uncommitted work in it rather than taking it with the folder, and it never removes the repository itself.</p>
-
- <h3>Several agents at once</h3>
- <p>A coding session can send work to sub-agents and run them in parallel. A rail shows what each one is doing and what it has cost, and one button stops all of them.</p>
+ <section id="shortcuts">
+ <h2><span class="icon">⌨️</span> Chat Commands</h2>
+ <p>Type <code>/</code> in the chat input to open the command picker. Available commands:</p>
- <h3>Your terminal</h3>
- <p>Under the box you type into, a real terminal: your login shell, in the session&rsquo;s folder, with your profile. Not a command field, so <code>vim</code>, <code>top</code>, an interactive prompt, colours, arrow keys and Ctrl-C all behave the way they do anywhere else. Open it with the switch in the title bar or by typing <code>/terminal</code>, drag its top edge to resize it, and open more than one tab if you want.</p>
- <div class="warn">
- <strong>🧵 Two shells, never mixed</strong> &mdash; The terminal is <em>yours</em>: your hands, your rights, and the agent can neither see it nor type into it, which is why it needs none of the agent&rsquo;s rules. What the <em>agent</em> runs is the other one, and it goes through every guard above.
+ <div class="shortcut-list">
+ <div class="shortcut-item"><div class="shortcut-key">/model</div><div class="shortcut-desc">Switch the active AI model inline (e.g. <code>/model claude-opus-4</code>)</div></div>
+ <div class="shortcut-item"><div class="shortcut-key">/new</div><div class="shortcut-desc">Start a new chat session</div></div>
+ <div class="shortcut-item"><div class="shortcut-key">/memory</div><div class="shortcut-desc">Show or search remembered facts</div></div>
+ <div class="shortcut-item"><div class="shortcut-key">/clear</div><div class="shortcut-desc">Clear current session messages</div></div>
+ <div class="shortcut-item"><div class="shortcut-key">/kill</div><div class="shortcut-desc">Stop any running Autopilot task immediately</div></div>
+ <div class="shortcut-item"><div class="shortcut-key">/help</div><div class="shortcut-desc">Show the full command list</div></div>
</div>
-
- <h3>Commands that do not end</h3>
- <p>A dev server, a watcher, a long build used to be a choice between a timeout and a blocked session. The agent can now start one in the background: its output appears under the step that started it and grows while you watch, and a strip above the status line lists everything that is running with what it is, how long it has been going, and a stop button. Nothing limits how many run and nothing times them out. Stopping stops the whole tree, so a port really comes free. A session that ends ends its own; so does closing Skales. Your phone can see the same list and press the same stop.</p>
-
- <h3>Typing: @, drag, and /</h3>
- <p>Typing <code>@</code> offers the files of the repository, matched on the whole path so a folder name finds them. Drop files onto the box, paste a screenshot, or use the paperclip: video, audio, PDFs and archives attach the way they do in a chat. A slash at the <em>start</em> of a line opens the commands a coding session has: switch mode, open review, commit, open a pull request, stop, start a new session, clear, open the terminal. A slash anywhere else is just a path.</p>
-
- <h3><code>/clear</code>, and where the work lives</h3>
- <p><code>/clear</code> starts the conversation over without losing the folder, the branch or your place. Each session also has a scratchpad of its own for the files it needs while it works, kept apart from your workspace and removed with the session.</p>
-
- <h3>Instructions: AGENTS.md and the order they win in</h3>
- <p>A coding session reads three things, most specific last: the project&rsquo;s own <code>CLAUDE.md</code> or <code>AGENTS.md</code>, then your global coding instructions, then anything you set for that one session. Put a project&rsquo;s rules in an <code>AGENTS.md</code> at its root and every session on that project follows them. The gear in the Code window edits the global and the per-session boxes; both show an example of what belongs in one &mdash; the language to answer in, your own test command, your commit style, your no-gos &mdash; as a hint, never as content.</p>
-
- <h3>It hears you while it is working</h3>
- <p>Type while a session is running and your message joins the run instead of starting a second one on the same transcript, and Skales says so.</p>
-
- <h3>Code inside a chat</h3>
- <p>A chat can still be bound to a folder and run in a code mode, and it is the same engine. A chat like that has one button in its header that stops what is running, cleanly, and hands the same session to the Code window &mdash; not a link and not a copy.</p>
- </section>
-
- <section id="chat-code-settings">
- <h2><span class="icon">⌨️</span> Settings: Chat &amp; Code</h2>
- <p>One tab in Settings for how Skales writes and how it codes.</p>
- <h3>Standing instructions: SKALES.md and AGENTS.md</h3>
- <p>Two boxes, two jobs, and the toggle above them says which you are editing.</p>
- <ul>
- <li><strong>SKALES.md</strong> is how you want to be <em>answered</em>, everywhere: answer in German, keep it short, never open with a compliment. It travels with every conversation, with tasks and schedules that run while you are away, and with your own agents.</li>
- <li><strong>AGENTS.md</strong> is how you want work <em>done</em> in a project: the test command, the commit style, the folders nothing may touch. It belongs to a project, at its root, and every coding session on that project reads it.</li>
- </ul>
- <p>Both are plain files &mdash; the path is printed under the box, and editing the file in a text editor is the same edit. If it changed on disk while you had unsaved text in the box, Skales says so rather than writing over it. Two places leave your standing instructions out on purpose: an isolated agent, which carries nothing of yours by design, and the calls Skales makes to itself.</p>
- <h3>Priority</h3>
- <p>Most specific wins: <strong>the project&rsquo;s own file</strong>, then <strong>your global instructions</strong>, then <strong>this session</strong>. A rule you set for one session beats the same rule set globally, and a project that ships its own conventions beats both.</p>
- <h3>The rest of the tab</h3>
- <p><strong>Shell command timeout</strong> sets how long a single command may run before Skales stops it (a command started in the background is not timed at all). <strong>Deep reasoning</strong> asks any model to think a problem through before acting, including models with no reasoning mode of their own. <strong>Code model</strong> runs a strong model for code while your chat stays on your default.</p>
- </section>
-
- <section id="sidebar">
- <h2><span class="icon">🗂️</span> Home and Work</h2>
- <p>The sidebar has a personal side and a working side, and the switch at the top decides which one you are looking at. The point is that a sidebar with thirty entries is a sidebar nobody reads.</p>
- <p>What the switch actually swaps is the <strong>Main</strong> group and the third group under it. Everything else stands in both.</p>
- <ul style="margin: 0.75rem 0 1rem 1.5rem; color: var(--muted); font-size: 0.875rem;">
- <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Main, on both sides.</strong> Dashboard, Chat, History, Discover, Memory. Somebody working has the same two questions as somebody at home — talk to it, and find what was said — so having to leave Work to ask them would make the switch a toll rather than a view.</li>
- <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Main, Home only.</strong> Lio AI.</li>
- <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Main, Work only.</strong> Code, Organization, Autopilot, Teams. Code and Teams stand there whatever the Add-Ons page says, because a Work side that can end up identical to Home is a switch that earns nothing.</li>
- <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Workspace, on both sides.</strong> Iris Orbit, Studio, Agents, Tasks, Schedule, Planner, Projects.</li>
- <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Personal (Home) / Build (Work).</strong> Home shows Browser, Group Chat, Spaces, Wrapped. Work shows Codework, Browser, Playbooks, Workflow, WordPress, Swarm.</li>
- <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Custom Widgets and System, on both sides.</strong> Skales Mobile, Add-Ons, Custom Skills, Custom Widgets, Templates, Logs, Update.</li>
- </ul>
- <p>An entry whose add-on is switched off is simply not in the list. Nothing is lost either way: the side you were on is remembered, and the page you are actually on is always visible in the sidebar, so a link or a finished task can never land you somewhere the menu does not show.</p>
- </section>
-
- <!-- Add-Ons and the two Settings views (12.7.0) -->
- <section id="addons-view">
- <h2><span class="icon">🧩</span> Add-Ons, and the two views of Settings</h2>
- <p>Skales can do a great many things, and nobody uses all of them. Two controls decide how much of that you have to look at, and neither of them turns anything off that you switched on.</p>
-
- <h3>The Add-Ons page</h3>
- <p><strong>Sidebar → System → Add-Ons.</strong> One card per add-on, one switch each. An add-on that has a page of its own puts that page in the sidebar while it is on and takes it away again when it is off; an add-on that needs an account says which key it needs and where to put it.</p>
- <p>Nine things are not on the list because they are not a choice: weather, summarizing, documents, web search, the system monitor, local file chat, screenshots and vision, VirusTotal and Wrapped. Switching those off would make Skales worse at being Skales, and nobody came to a setup screen to decide them.</p>
- <p>The five categories in the setup screen are a shortcut into the same switches, not a mode. Picking <em>Coding AI</em> preselects that bundle; what gets stored is the add-ons, not the category.</p>
-
- <h3>Standard and Advanced</h3>
- <p>The switch at the top of <strong>Settings</strong> chooses between two views of the same page.</p>
- <ul style="margin: 0.75rem 0 1rem 1.5rem; color: var(--muted); font-size: 0.875rem;">
- <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Standard</strong> shows the settings your add-ons actually need, plus the ones everybody needs. A section that belongs to an add-on you have not switched on is not there.</li>
- <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Advanced</strong> shows every setting there is, exactly as before.</li>
- </ul>
- <p>It is a <em>view</em>, not a state. Anything you switched on in Advanced stays on in Standard — it is only out of sight. Search reaches both views, so typing what you are looking for finds it whichever one you are in, and a tab that would open onto an empty page in Standard is not offered.</p>
- <p>The Advanced view is not a list of dangerous things. Diagnostics, Updates, Export/Import and the data controls all sit in the <strong>Advanced tab</strong> and are all shown in the Standard view, because those are things ordinary users are sent to.</p>
-
- <h3>Changing your mind</h3>
- <p><strong>Settings → Advanced → Setup</strong> runs the add-on screen again. Nothing is deleted by it: chats, keys and settings stay exactly as they are, and only what is shown changes.</p>
- </section>
-
- <section id="accents">
- <h2><span class="icon">🎨</span> Your own accent colours</h2>
- <p>Under <strong>Settings &gt; Appearance</strong> you can set the three accent tones Skales uses for buttons, links, glows and selections. Skales keeps them readable rather than taking them literally: a tone that would leave text unreadable on your theme is adjusted in brightness until it is, so a colour you like cannot turn a label into a rumour.</p>
- <p>One thing accents never touch: the Skales lettering in the sidebar keeps its own colours in every theme, because that is the brand, not a control. Skales Code follows the same accents and the same light or dark as the app, and changes the moment you change it.</p>
</section>
- <!-- GOAL (v11) -->
<section id="goal">
<h2><span class="icon">🎯</span> GOAL</h2>
<p>GOAL turns Skales from a chat you steer one reply at a time into an agent that holds a goal and works it across many steps on its own. Type <code>/goal</code> followed by what you want, or describe something big enough that Skales offers to take it on, then let it plan, act, check its own progress, and decide when it is done.</p>
@@ -901,180 +1275,144 @@
<div class="tip"><strong>💡 Tip:</strong> Put several models in one thread to talk a goal through together. See <a href="#group-chat" style="color:var(--accent)">Group Chat</a>.</div>
</section>
- <!-- Studio -->
- <section id="studio">
- <h2><span class="icon">🎨</span> Skales Studio</h2>
- <p>An all-in-one AI creative suite built into Skales. Generate images, videos, voice audio, and music — all from a single interface. Every output is saved to your Gallery and can be reused at any time.</p>
-
- <h3>Image Generation</h3>
- <p>Describe what you want and choose your provider. Skales Visuals is the built-in renderer. For higher resolution or photorealism, connect Replicate (Flux, SDXL), HuggingFace, OpenAI DALL-E, or a local ComfyUI/Stable Diffusion WebUI instance. Export as PNG.</p>
-
- <h3>Video Creation</h3>
- <p>Describe a motion graphic in plain language — counters, text animations, infographics, slideshows, social posts. Skales Studio renders it instantly in the live preview. Iterate with follow-up instructions. When you're happy with the result, export as MP4 using the built-in FFmpeg renderer. Categories: Text Animation, Infographic, Data Visualization, Logo Intro, Slideshow, Social Post, Counter/Stats.</p>
-
- <h3>Type</h3>
- <p>Open <strong>Sidebar → Studio → Type</strong> to turn a line of text into an animated, looping video (kinetic typography), with no AI and no setup. The headline is a set of <strong>14 Motion presets</strong> driven by a real timeline engine, with custom easing, per-letter staggers and depth: Cascade, Drop, Pop, Bounce, Slide, Reveal, Flip 3D, Spin, Wave, Breathe, Glitch, Neon, Shine, Typewriter. Pick one and it just works, there is nothing to configure. Below them are 18 simpler presets, including real 3D ones: Fade, Rise, Slide, Typewriter, Word cascade, Letter pop, Zoom in, Zoom blast, Blur focus, 3D flip, 3D swing, Cube roll, Depth dive, Wave, Neon, Glitch, Reveal, Expand. Set the font, weight, text color, background (presets including a Skales-X theme and a Transparent option), aspect (9:16, 16:9, 1:1, 4:5), duration, font size, and a Loop toggle. Watch the live preview, then Export. A transparent background exports an alpha WebM (VP9) you can lay over other footage; otherwise you get an MP4. It uses the same HTML-to-frames-to-FFmpeg pipeline as Studio's other video, so every frame is exact.</p>
+ <section id="documents">
+ <h2><span class="icon">📄</span> Document Generation</h2>
+ <p>Create Excel (.xlsx), Word (.docx), and PDF files from natural language. Ask "create a budget spreadsheet" and Skales generates it.</p>
- <h3>Voice / TTS</h3>
- <p>Paste or type a script and generate speech. Skales auto-detects your available TTS provider: Local (OS voices), ElevenLabs, Azure Neural TTS, Groq TTS, OpenAI TTS, or Google TTS. Preview in-app, then download as MP3.</p>
+ <h3>Excel (.xlsx)</h3>
+ <p>Generate spreadsheets with formulas, formatting, and multiple sheets. Skales can create budgets, tables, charts, and data compilations.</p>
- <h3>Music Generation</h3>
- <p>Generate AI music via Meta MusicGen (HuggingFace). Select genre, mood, and duration. Preview and download the result directly from the Studio interface.</p>
+ <h3>Word (.docx)</h3>
+ <p>Generate formatted documents with headings, paragraphs, tables, and lists. Perfect for reports, proposals, and technical documentation.</p>
- <h3>Gallery</h3>
- <p>Every Studio output — images, videos, audio — is automatically saved to your Gallery. Filter by type, search by prompt, or browse the masonry grid. Click <strong>Reuse</strong> on any entry to jump back to the generating tab with the prompt and preview restored so you can continue iterating.</p>
+ <h3>PDF Export</h3>
+ <p>Convert documents to PDF format. PDFs are fully formatted and ready for sharing or printing.</p>
- <h3>Brand Kit</h3>
- <p>Configure your brand once in <strong>Studio → Brand Kit</strong>: logo, primary colors, fonts, tagline, and tone of voice. Enable the <em>Use Brand Kit</em> checkbox in Image or Video generation to automatically inject brand context into every prompt.</p>
+ <h3>Designed PDF (html_to_pdf)</h3>
+ <p>For a designed or visual PDF, such as a brochure, a product sheet, or a branded report, the agent calls the <strong>html_to_pdf</strong> tool, which renders an HTML string into a clean, print-ready A4 PDF: proper page breaks, backgrounds and colors printed, and no browser print header or footer with file paths or timestamps. This is the right way to produce a layout-heavy PDF instead of shelling out to <code>chrome</code> or <code>edge --print-to-pdf</code>. Plain editable text still uses <strong>create_document</strong>, and data tables use <strong>create_spreadsheet</strong>.</p>
- <div class="tip"><strong>💡 Tip:</strong> All Studio files are stored under <code>~/.skales-data/studio/</code>. Images go to <code>gallery/</code>, videos to <code>videos/</code>. Filenames are prefixed with <code>skales_studio_</code>.</div>
+ <h3>Dynamic Templates</h3>
+ <p>Describe what you need and Skales generates appropriate structure and content. No template library required.</p>
</section>
- <!-- Templates -->
- <section id="flow">
- <h2><span class="icon">🌊</span> Flow</h2>
- <p>Flow is Studio&rsquo;s conversational design workspace: one brief, and it keeps working on it with you instead of returning a single result. Nine modes, and Flow picks the one that fits what you asked unless you say otherwise: <strong>deck</strong>, <strong>prototype</strong>, <strong>wireframe</strong>, <strong>mobile</strong> mockup, print <strong>document</strong>, <strong>image</strong>, <strong>video</strong>, <strong>film</strong> and <strong>motion</strong> graphic.</p>
- <h3>Film: one shot, one camera move</h3>
- <p>Film makes a single clip with a single deliberate camera move, and the move is what you pick first &mdash; before you write a word of the brief. Fifty-one of them, grouped by what they are: zoom, dolly, crane, pan, orbit, rig, aerial and lens. One move per clip, and there is no way to pick two: mixing camera moves in one generated shot is exactly what makes generated footage look generated.</p>
- <p>Where the clip comes from, in this order:</p>
- <ol>
- <li><strong>Higgsfield</strong>, if you have connected it as an MCP server under Settings. It executes a camera preset as a preset rather than as words, so it gives the best result for this mode.</li>
- <li><strong>The video APIs under Settings &rsaquo; Skales Studio</strong> &mdash; Kling, Runway, fal, Google Veo, Replicate or OpenRouter. None of them takes a camera-move parameter, so the move you picked steers the prompt instead. This is the normal path and it works well.</li>
- <li><strong>A Hugging Face Space you have activated</strong>, as the budget route: free or nearly so, on a shared queue, and slower.</li>
- </ol>
- <p>If none of the three is set up, the chip stays where it is and tells you which key is missing and where it goes. It keeps the camera move you picked either way. Follow-up messages are takes: &ldquo;tighter&rdquo;, &ldquo;try it as a crane up&rdquo;, &ldquo;same shot at night&rdquo; keep everything you did not change and save the result beside the earlier takes.</p>
- <p>On the phone, Film works the same way with the same moves, and generates through the video key on the phone (fal.ai under Integrations, or an OpenRouter key under Provider). With no key it says so rather than producing an animation and calling it a film.</p>
- <h3>Nothing you made is gone</h3>
- <p>Every turn seals a version of the whole project, so you can go back to any of them &mdash; and the rollback is itself sealed first, which is what keeps going back reversible. Projects can be archived (reversible, keeps everything) or deleted (the folder moves to a trash folder next to your projects).</p>
- <h3>Brand Kit and style packs</h3>
- <p>Your Brand Kit &mdash; logo, colours, fonts, tone &mdash; applies to a Flow project, and a style pack can be pinned next to it. Your brief always wins on content.</p>
- <h3>Handing it to Code</h3>
- <p>A design in Studio or Flow can be handed to the coding session that will build it, so the thing you approved is what gets built.</p>
+ <section id="http-request">
+ <h2><span class="icon">🔌</span> Calling an API</h2>
+ <p>Skales can talk to any REST API or submit a web form: your method, your headers, your body, and the answer back. A body shaped like <code>name=Ada&amp;message=Hello</code> is sent as a form, which is the difference between a request that works and one that quietly does nothing. Reading runs; writing (POST, PUT, PATCH, DELETE) asks first, like any other writing action.</p>
+ <h3>What it can reach</h3>
+ <p>The internet, your own network and your tailnet: a NAS, a second machine, a service you run at home are all normal targets. <strong>This computer is not</strong>, because that is where Skales itself listens, and a web page or a document could otherwise talk the agent into calling the app on your behalf. Link-local and cloud metadata addresses are never allowed.</p>
+ <p>If you want the agent to reach a service you run locally, turn on <strong>Let http_request reach this computer</strong> under <strong>Settings &gt; Security</strong>. It is off by default and the text says why. It is an outbound rule for this one tool: how <em>you</em> reach Skales from your phone or over Tailscale is a separate setting and is untouched by it.</p>
</section>
- <section id="templates">
- <h2><span class="icon">🗂️</span> Templates</h2>
- <p>37 pre-built prompt templates spanning every Skales module. Click any template to open the target module with the prompt already filled in — no copy-pasting required.</p>
-
- <h3>Template Categories</h3>
+ <section id="easter-eggs">
+ <h2><span class="icon">🦎</span> Easter Eggs</h2>
+ <p>Skales has a few hidden, playful extras. None of them change your work or cost a thing, they are just for fun. You can also ask Skales any time which easter eggs it has and it will list them.</p>
+ <h3>Type these in the chat</h3>
+ <ul>
+ <li><code>/coffee</code> &middot; a tongue-in-cheek &ldquo;still brewing&rdquo; reply.</li>
+ <li><code>/servus</code> &middot; a Viennese hello back.</li>
+ <li><code>/wien</code> or <code>/vienna</code> &middot; a greeting from Vienna with an ASCII Stephansdom.</li>
+ <li><code>/sachertorte</code> &middot; the authentic Vienna Sachertorte recipe card.</li>
+ <li><code>/nudge</code> &middot; shakes the Desktop Buddy window, MSN Messenger style.</li>
+ <li><code>/barrelroll</code> or <code>/do a barrel roll</code> &middot; spins the chat a full 360 degrees.</li>
+ <li><code>/highfive</code> and <code>/bow</code> &middot; an animated 🙌 and 🙏.</li>
+ <li><code>:gecko:</code> 🦎, <code>:bubbles:</code> 🫧, <code>:paw:</code> 🐾 &middot; inline animated emoji.</li>
+ </ul>
+ <h3>Hidden interactions</h3>
+ <ul>
+ <li><strong>The Konami code</strong> (up, up, down, down, left, right, left, right, B, A) unlocks a gecko surprise.</li>
+ <li><strong>Click the Skales logo seven times</strong> to collect the seven secrets; all seven earns the &ldquo;Master of Geckos&rdquo; badge.</li>
+ <li><strong>Shake the Desktop Buddy window</strong> three times fast and it asks you to stop shaking the gecko. <code>Cmd/Ctrl + Shift + N</code> does the nudge from anywhere.</li>
+ <li><strong>Start a fresh chat with &ldquo;hello skales&rdquo;</strong> (or hi / hey skales) for a personal greeting.</li>
+ </ul>
+ </section>
+
+ <section id="memory">
+ <h2><span class="icon">🧠</span> Memory</h2>
+ <p><strong>Bi-Temporal Memory</strong> — Auto-extracts facts and preferences from conversations. Skales builds a persistent understanding of who you are over time, storing memory locally and injecting relevant context before every reply.</p>
+
<table>
- <thead><tr><th>Category</th><th>Examples</th></tr></thead>
+ <thead><tr><th>Type</th><th>What it stores</th></tr></thead>
<tbody>
- <tr><td>Chat</td><td>Research briefing, email rewrite, document summary</td></tr>
- <tr><td>Codework</td><td>Refactor for readability, add unit tests, migrate to TypeScript</td></tr>
- <tr><td>Organization</td><td>Marketing campaign, competitive analysis, product spec</td></tr>
- <tr><td>Lio AI</td><td>Landing page, dashboard component, data visualizer</td></tr>
- <tr><td>Browser</td><td>Price comparison, news digest, form auto-fill</td></tr>
- <tr><td>Planner</td><td>Weekly agenda, project breakdown, task prioritizer</td></tr>
- <tr><td>Studio</td><td>Brand intro video, podcast cover art, social post graphic</td></tr>
+ <tr><td>Short-term</td><td>Facts from the current session — names, preferences, context</td></tr>
+ <tr><td>Long-term</td><td>Extracted highlights across sessions — important facts, decisions, habits</td></tr>
+ <tr><td>Episodic</td><td>Notable conversations and events timestamped for recall</td></tr>
</tbody>
</table>
- <h3>Template Maker</h3>
- <p>Build your own templates with the AI-guided interview wizard. Describe your use case, and the Template Maker generates a reusable prompt with the right structure, placeholders, and target module. Custom templates are stored locally and can be shared via the Discover Feed.</p>
-
- <div class="tip"><strong>💡 Tip:</strong> Templates shared to Discover can be forked by other users — a great way to share your best workflows with the community.</div>
- </section>
+ <p>Manage memories in <strong>Settings → Memory</strong>. You can view, edit, or delete individual entries. Up to 5 relevant memories are automatically recalled per conversation.</p>
- <!-- AI Tasks -->
- <section id="ai-tasks">
- <h2><span class="icon">⏰</span> Planner AI Tasks</h2>
- <p>Schedule AI tasks to run automatically — once, daily, weekly, or monthly. Tasks are visible in the Planner calendar as purple blocks and execute silently in the background.</p>
+ <h3>Adapts to how you work</h3>
+ <p>Over time Skales builds a quiet sense of how you like to work and folds it into memory, and it distills the approaches that carried past goals to a finish into reusable plans. Now and then it surfaces one short question to understand you better, never while it is busy and never often, with a quiet notification and a dot next to Chat so it is not missed. You can set your agent's character outright when you join Discover, and clear everything Skales has picked up about you at any time, from Settings or right in the chat.</p>
- <h3>Creating a Task</h3>
- <p>Open <strong>Planner → AI Tasks</strong>, click <strong>New Task</strong>, describe what the AI should do, and set a schedule. The task is saved with a cron expression and fires automatically at the specified time.</p>
+ <h3>Shared Organization Memory</h3>
+ <p>Organization teams have their own shared memory pool. Team members read and write shared context — project decisions, research findings, meeting notes — that persists across execution runs. Shared memory is separate from your personal memory and managed in the Organization settings.</p>
+ </section>
- <h3>Confidence Scoring</h3>
- <p>Before executing, the AI scores its confidence in completing the task safely (0–100%). Tasks scoring below 50% are skipped automatically and flagged for review, preventing accidental destructive actions.</p>
+ <section id="memory-mode">
+ <h2><span class="icon">⚙️</span> Memory Mode</h2>
+ <p>Controls how much of your conversation Skales keeps in context on every request. Trade off quality against token cost without changing models.</p>
- <h3>Dry Run Mode</h3>
- <p>Enable Dry Run to simulate task execution without actually performing any actions. The AI describes exactly what it would do — useful for testing tasks before activating them on a live schedule.</p>
+ <h3>Three Modes</h3>
+ <div class="card-grid">
+ <div class="card"><div class="card-title">Always Remember</div><div class="card-desc">Full system prompt, full memory, full skills, full tool capabilities. Highest quality, highest token cost.</div></div>
+ <div class="card"><div class="card-title">Compact</div><div class="card-desc">Older context trimmed and recalled memories capped at 2. Roughly 40% fewer tokens while keeping the day-to-day experience intact.</div></div>
+ <div class="card"><div class="card-title">Minimal</div><div class="card-desc">Name, language, and active tool list only. No memory, no identity. Roughly 70% fewer tokens, best for quick one-shot questions.</div></div>
+ </div>
- <h3>Task History</h3>
- <p>Each task run is logged with the tools used, duration, and a summary of the result. Review the history from the AI Tasks panel to audit what ran and when.</p>
+ <h3>Configure in Settings</h3>
+ <p>Pick your default mode under <strong>Settings → Memory Mode</strong>. Minimal lives behind an Advanced disclosure since it strips identity and memory; click the disclosure to access it. The header badge in Chat surfaces when your saved mode is anything other than Always Remember.</p>
- <div class="tip"><strong>💡 Tip:</strong> Browser Playbooks can be scheduled as AI Tasks — record a workflow once, then let Skales replay it on a recurring schedule.</div>
+ <h3>Auto-tune for Local Models</h3>
+ <p>Local providers (Ollama, LM Studio, KoboldCpp, vLLM) typically run with an 8k context budget. With auto-tune enabled, Skales silently runs in Compact on those providers even when your saved mode is Always Remember, so the prompt fits without truncation surprises.</p>
</section>
- <!-- Browser -->
- <section id="browser">
- <h2><span class="icon">🌐</span> Browser <span class="badge badge-beta">Beta</span></h2>
- <p>A built-in browser with AI co-pilot. Navigate the web and ask Skales to help you while browsing.</p>
+ <section id="knowledge-graph">
+ <h2><span class="icon">🕸️</span> Knowledge Graph</h2>
+ <p>An enterprise-grade knowledge graph that builds relationships between entities as you work. Skales learns about your projects, people, tools, and preferences and connects them automatically.</p>
- <h3>How it works</h3>
- <p>Type a command in the input bar (e.g. <em>"Go to hacker news and summarize the top 5 stories"</em>). Skales navigates, reads the page, and responds — up to 10 agentic steps per command.</p>
+ <h3>How It Works</h3>
+ <p>As agents complete tasks, they extract entities (projects, contacts, tools, decisions) and record relationships between them. The graph grows organically without manual input.</p>
- <h3>Session Controls</h3>
+ <h3>Agent Tools</h3>
<table>
- <thead><tr><th>Control</th><th>Description</th></tr></thead>
+ <thead><tr><th>Tool</th><th>Description</th></tr></thead>
<tbody>
- <tr><td>+ New Session</td><td>Clears the current page and conversation log, starts fresh at Google</td></tr>
- <tr><td>↩ Refresh</td><td>Reloads the current page</td></tr>
- <tr><td>⬇ Export</td><td>Downloads the conversation log as a Markdown file (visible when log has entries)</td></tr>
+ <tr><td>knowledge_graph_query</td><td>Search and retrieve related entities</td></tr>
+ <tr><td>knowledge_graph_update</td><td>Add or update entities and relationships</td></tr>
+ <tr><td>knowledge_graph_delete</td><td>Remove entities from the graph</td></tr>
</tbody>
</table>
- <h3>Conversation Log</h3>
- <p>The last 5 exchanges are shown above the input bar — your commands (→) and Skales' responses (🦎). Full history is exported with the Markdown button.</p>
-
- <h3>Sign in to sites (v12.3.0)</h3>
- <p>When a task needs you logged in (X, Reddit, a webshop), Skales opens a visible browser window so you can sign in by hand. Your login is saved to the Skales browser profile and reused by later browsing. Skales never sees your password. Open a login window any time from Settings → Browser Control ("Log in to a website"), or turn on "Show browser window" there to watch Skales work. When it reads a page, Skales now uses a compact text map of the page instead of a Vision screenshot for each step, which is faster and cheaper; screenshots are still used for image-heavy pages.</p>
+ <h3>Management</h3>
+ <p>Enable, disable, or fully reset the knowledge graph in <strong>Settings → Knowledge Graph</strong>. Disabling stops new data from being added but preserves existing relationships.</p>
</section>
- <!-- Planner -->
- <section id="planner">
- <h2><span class="icon">📅</span> Planner <span class="badge badge-beta">Beta</span></h2>
- <p>AI-powered daily planner that learns your work patterns. An 8-step wizard learns your preferences, generates time-blocked plans from calendar events, and pushes them back to your calendar. Chat integration with "plan my day" commands.</p>
-
- <h3>8-Step Wizard</h3>
- <p>On first use, a guided wizard learns your work patterns, available hours, break preferences, and constraints. This context is used to personalize all future plan generation.</p>
-
- <h3>Month View</h3>
- <p>The default calendar view shows the entire month at a glance. Click on any day to see detailed plans.</p>
-
- <h3>Daily Context</h3>
- <p>Add day-specific notes directly in your planner (e.g., <strong>"I'm busy at 12:00"</strong> or <strong>"Important deadline"</strong>). The AI uses this context to generate smarter schedules around your constraints.</p>
-
- <h3>Generate & Regenerate</h3>
- <p>Use <strong>Generate</strong> to create a new daily plan from your calendar events, or <strong>Regenerate</strong> to try again with different AI reasoning. Plans are automatically saved and synced back to your calendar.</p>
+ <section id="vector-db">
+ <h2><span class="icon">🗄️</span> External vector database</h2>
+ <p>Skales keeps its own index of the documents you add to it: keyword search, plus a vector index when embeddings are configured. If you already run <strong>Qdrant</strong> or <strong>ChromaDB</strong> and your corpus is already in it, you can point Skales at that collection instead of importing everything a second time. <strong>Settings &rarr; Memory &rarr; External vector database</strong>.</p>
+ <p>Fill in the server URL, the collection name, and an API key if your server needs one. <strong>Test connection</strong> runs one real query and shows the database's own answer, because a dimension mismatch, a collection name that does not exist and a rejected key are three different problems and only the server can tell them apart.</p>
- <h3>.ICS Export</h3>
- <p>Download plans as <code>.ics</code> files for use with any calendar application — no provider connection needed.</p>
+ <h3>What changes, and what does not</h3>
+ <ul>
+ <li><strong>Skales only reads.</strong> It never writes to your collection, never creates one, never deletes anything. Your corpus is yours.</li>
+ <li><strong>Only the vector half is swapped.</strong> Keyword search over the documents you added to Skales keeps running alongside it, so both kinds of document stay findable rather than one hiding the other.</li>
+ <li><strong>It falls back.</strong> If the database is unreachable, or the collection is wrong, or the key is refused, Skales uses its own store for that search instead of failing. You get a slightly worse answer rather than an error.</li>
+ </ul>
- <h3>Chat Integration</h3>
- <p>In chat, ask "plan my day" or "schedule my week" and Skales will generate plans directly from context.</p>
+ <div class="warn"><strong>⚠️ One thing to get right</strong> &mdash; use the same embedding model the collection was built with. A question embedded by a different model lands in a different space and comes back confidently wrong. Skales cannot detect that for you: a vector of the right size from the wrong model looks exactly like the right one.</div>
</section>
- <!-- Autopilot -->
- <section id="autopilot">
- <h2><span class="icon">⚡</span> Autopilot</h2>
- <p>Background task runner with a Kanban board. Delegate long-running tasks and Skales will execute them autonomously while you work on other things.</p>
-
- <h3>Task Board</h3>
- <p>Tasks move through: <strong>Pending → In Progress → Done</strong>. You can review results, retry failed tasks, or cancel in-progress ones.</p>
-
- <h3>Live Execution</h3>
- <p>Watch Skales think through each step in real time. Tool calls, decisions, and results are shown as they happen.</p>
-
- <h3>Cost Control</h3>
- <p>Set a max API calls per hour in Settings → Autopilot to prevent runaway costs. Autopilot pauses automatically when the limit is reached.</p>
-
- <div class="tip"><strong>💡 Tip:</strong> Autopilot must be enabled in Settings → Autopilot → Enable Autopilot for background task processing. Friend Mode and Buddy Intelligence work independently of this toggle.</div>
-
- <h3>A plan you read before it exists</h3>
- <p>The Deep-Dive interview ends in a Master Plan, and the plan is a <em>draft</em>: a list of tasks you read, untick and edit. Nothing is created until you press &ldquo;Create these&rdquo;. If the model got one task wrong, the rest survive and the ones that were left out are named with the reason.</p>
-
- <h3>Quick Task</h3>
- <p>Type one line and Skales works it up into a task an agent can actually run: instructions, the project it belongs to and the agent best suited to it. Each of the three is a suggestion with a tick beside it; untick whatever is wrong. If Autopilot is paused, the warning carries the switch itself, so the task you just made can start without going anywhere else.</p>
+ <section id="auto-compress">
+ <h2><span class="icon">📦</span> Auto-Compress</h2>
+ <p>Conversations automatically compress when they exceed the model's context window. Skales summarizes older messages to free up token space while preserving important context, allowing conversations to continue indefinitely without manual intervention.</p>
- <h3>The board</h3>
- <p>Drag a card to another column to move it. Two moves are refused rather than faked: you cannot drop a card into &ldquo;in progress&rdquo;, because that is where Skales puts a task when it actually picks it up, and you cannot drag a task that is running out from under the runner &mdash; cancel it first.</p>
+ <h3>How It Works</h3>
+ <p>When your conversation approaches the token limit, Skales generates a concise summary of the oldest messages and replaces them with the compressed version. Key facts, decisions, and context are retained. The compression is seamless — you can keep chatting without interruption.</p>
- <h3>Running goals</h3>
- <p>The strip above the board shows the goals running across all your conversations. Each one opens where it lives, and can be carried on or stopped from here.</p>
-</section>
+ <h3>Token Budget</h3>
+ <p>Works alongside the Memory Mode setting. Auto-Compress handles conversation history, while Memory Mode handles system prompt size. Together they maximize how much useful context fits in every request.</p>
+ </section>
- <!-- Agents -->
<section id="agents">
<h2><span class="icon">🤖</span> Agents</h2>
<p>Create custom AI personas with their own name, personality, system prompt, and model selection. Agents appear in the chat persona picker and each maintain a separate conversation history.</p>
@@ -1095,7 +1433,6 @@
<p>This is one of three multi-agent modes, and they are not interchangeable. <a href="#multi-agent" style="color:var(--accent)">Which multi-agent mode</a> lays out what each one is for, and how to run a team on a single graphics card.</p>
</section>
- <!-- Which multi-agent mode -->
<section id="multi-agent">
<h2><span class="icon">🧭</span> Which multi-agent mode</h2>
<p>Skales has three ways to put more than one agent on something, and they are genuinely different machines rather than three names for one. They differ in who writes the question each agent gets, whether the agents can see each other, whether they may use tools, and what you are left holding at the end.</p>
@@ -1139,30 +1476,89 @@
<div class="tip"><strong>💡 Short version:</strong> want opinions &rarr; Parallel answers. Want a conversation &rarr; Group Chat. Want a result &rarr; Organization.</div>
</section>
- <!-- Memory -->
- <section id="memory">
- <h2><span class="icon">🧠</span> Memory</h2>
- <p><strong>Bi-Temporal Memory</strong> — Auto-extracts facts and preferences from conversations. Skales builds a persistent understanding of who you are over time, storing memory locally and injecting relevant context before every reply.</p>
+ <section id="group-chat">
+ <h2><span class="icon">👥</span> Group Chat</h2>
+ <p>Multiple AI personas debate your questions in configurable rounds. Perfect for exploring different perspectives and validating ideas.</p>
+ <p>Not sure whether you want a debate, several independent answers, or a finished piece of work? See <a href="#multi-agent" style="color:var(--accent)">Which multi-agent mode</a>.</p>
+
+ <h3>Custom Personas</h3>
+ <p>Select which agents participate in the debate. Each agent uses its own system prompt and personality to generate responses.</p>
+
+ <h3>Configurable Rounds</h3>
+ <p>Set the number of rounds for debate. Each round, agents respond to the previous turn's arguments.</p>
+
+ <h3>Unified View</h3>
+ <p>See all agent responses side-by-side with clear attribution. Toggle between full responses and summary mode.</p>
+ </section>
+
+ <section id="organization">
+ <h2><span class="icon">🏢</span> Organization</h2>
+ <p>Create multi-agent teams. Build departments, assign agents, and delegate tasks across your AI company.</p>
+ <p>How this differs from Group Chat and from asking several agents at once: see <a href="#multi-agent" style="color:var(--accent)">Which multi-agent mode</a>.</p>
+ <h3>Structure</h3>
<table>
- <thead><tr><th>Type</th><th>What it stores</th></tr></thead>
+ <thead><tr><th>Component</th><th>Description</th></tr></thead>
<tbody>
- <tr><td>Short-term</td><td>Facts from the current session — names, preferences, context</td></tr>
- <tr><td>Long-term</td><td>Extracted highlights across sessions — important facts, decisions, habits</td></tr>
- <tr><td>Episodic</td><td>Notable conversations and events timestamped for recall</td></tr>
+ <tr><td>CEO</td><td>Top-level agent that routes tasks to the right department</td></tr>
+ <tr><td>Departments</td><td>Engineering, Marketing, Operations (customizable)</td></tr>
+ <tr><td>Teams</td><td>Groups of agents within a department</td></tr>
+ <tr><td>Company Packs</td><td>Export/import your entire org setup as JSON</td></tr>
</tbody>
</table>
- <p>Manage memories in <strong>Settings → Memory</strong>. You can view, edit, or delete individual entries. Up to 5 relevant memories are automatically recalled per conversation.</p>
+ <h3>Canvas Office</h3>
+ <p>A real-time animated canvas visualization of your organization. Agents are rendered as interactive nodes on a 2D canvas with smooth animations, connection lines between team members, and status indicators. The canvas auto-scales to fit your org structure and uses requestAnimationFrame for 60fps rendering.</p>
- <h3>Adapts to how you work</h3>
- <p>Over time Skales builds a quiet sense of how you like to work and folds it into memory, and it distills the approaches that carried past goals to a finish into reusable plans. Now and then it surfaces one short question to understand you better, never while it is busy and never often, with a quiet notification and a dot next to Chat so it is not missed. You can set your agent's character outright when you join Discover, and clear everything Skales has picked up about you at any time, from Settings or right in the chat.</p>
+ <h3>Execute Tab with Live Polling</h3>
+ <p>Describe a task, select a team, and the CEO agent delegates it to the right agents. The Execute tab now features live step-by-step progress streaming — watch each agent's work unfold in real time with a scrolling log, elapsed timer, and abort button. Results are aggregated and returned when all subtasks complete.</p>
- <h3>Shared Organization Memory</h3>
- <p>Organization teams have their own shared memory pool. Team members read and write shared context — project decisions, research findings, meeting notes — that persists across execution runs. Shared memory is separate from your personal memory and managed in the Organization settings.</p>
+ <h3>Projects</h3>
+ <p>Save and manage reusable project configurations. Each project stores a name, description, selected team, and default instructions. Load a project to pre-fill the Execute tab instantly. Create, edit, and delete projects from the Projects panel.</p>
+
+ <h3>Shared Memory</h3>
+ <p>Organization agents share a dedicated memory pool separate from your personal chat memory. Team members can read and write shared context — meeting notes, project decisions, research findings — that persists across execution runs. Manage shared memories from the Organization settings.</p>
+
+ <h3>Safe Mode in Organization</h3>
+ <p>When Safe Mode is enabled, organization agents are instructed to avoid destructive actions. Instead of sending emails or running shell commands directly, agents prepare the content as files and report what they would have done. You can review and execute manually.</p>
+ <table>
+ <thead><tr><th>Mode</th><th>Behavior in Organization</th></tr></thead>
+ <tbody>
+ <tr><td>Safe Mode</td><td>Agents prepare emails as files, describe commands without executing. You review and send manually.</td></tr>
+ <tr><td>Unrestricted</td><td>Agents execute all actions including sending emails and running commands without confirmation.</td></tr>
+ </tbody>
+ </table>
+
+ <h3>Email in Organization</h3>
+ <p>Organization agents can now send emails as part of their workflows. In Unrestricted mode, the send_email tool executes immediately. In Safe Mode, agents save prepared emails as files for your review.</p>
+
+ <div class="warn"><strong>⚠️ Unrestricted Mode</strong> — In Unrestricted mode, organization agents execute all actions including emails and system commands without confirmation. Use with caution.</div>
+ </section>
+
+ <section id="swarm">
+ <h2><span class="icon">🐝</span> Agent Swarm <span class="badge badge-beta">Beta</span></h2>
+ <p>Run multiple Skales instances on your network and have them work as one. Peers are discovered automatically via <strong>mDNS</strong>, or added manually by <strong>IP:port</strong> (perfect for Tailscale) &mdash; manual peers survive restarts and are health-checked every 30 seconds.</p>
+ <p>Delegate from any chat: <code>/swarm &lt;task&gt;</code> sends to the best free device, <code>/swarm @name &lt;task&gt;</code> targets a specific one, and an optional mode prefix sets how the task runs on the receiver &mdash; <code>code:</code> (coding agent), <code>plan:</code> (read-only plan), <code>auto:</code> (fully autonomous). The Swarm page offers the same as a form, plus the shared task history with live status. Results return to the chat you sent from and to Notifications.</p>
+ <p><strong>Security:</strong> receiving devices must opt in (&ldquo;Accept delegated tasks&rdquo;) and both devices need the same <code>SKALES_AGENT_SECRET</code> environment variable. Delegated tasks appear on the receiver&rsquo;s Tasks page with a 🐝 badge naming the sender.</p>
+ </section>
+
+ <section id="agent-sync">
+ <h2><span class="icon">🤝</span> Agent-to-Agent Protocol</h2>
+ <p>Multi-Skales collaboration on the same network. The <code>/api/agent-sync</code> endpoint enables distributed task delegation and shared context.</p>
+
+ <h3>mDNS Discovery</h3>
+ <p>Skales instances automatically discover each other on local networks via mDNS. No manual configuration required.</p>
+
+ <h3>Task Delegation</h3>
+ <p>Send tasks to other Skales instances for parallel processing. Combine results into a unified response.</p>
+
+ <h3>Shared Context</h3>
+ <p>Share memory, settings, or conversation context between instances. Perfect for distributed teams or coordinated automation.</p>
+
+ <h3>Secure Communication</h3>
+ <p>Communication is encrypted and authenticated via local tokens. No external servers required.</p>
</section>
- <!-- Skills -->
<section id="skills">
<h2><span class="icon">🔧</span> Skills</h2>
<p>Skills extend what Skales can do. Built-in skills are always available. Custom skills can be created and shared.</p>
@@ -1187,7 +1583,6 @@
<p>Build your own skills in <strong>Settings → Custom Skills</strong>. Describe what the skill should do, and Skales generates the implementation. Skills are stored as JSON and can be exported and shared.</p>
</section>
- <!-- Agent Skills Import -->
<section id="agent-skills">
<h2><span class="icon">🧩</span> Agent Skills Import</h2>
<p>Skales natively supports the <strong>Agent Skills</strong> open standard (SKILL.md format) used by Claude Code, Codex, GitHub Copilot, and Cursor. Import skills to extend your agent's capabilities.</p>
@@ -1213,10 +1608,205 @@
<div class="tip"><strong>💡 Tip:</strong> Imported skills appear on the Custom Skills page. Toggle them on/off individually. Delete with the trash icon.</div>
</section>
- <!-- Codework -->
- <section id="codework">
- <h2><span class="icon">🛠️</span> Skales Codework</h2>
- <p>An autonomous coding agent built into Skales, with its own file tree, editor and terminal. Select any project folder, describe a task, and watch the AI work. For everyday coding the chat's Code mode (Chat / Code / Edits / Plan / Auto on a bound folder) is now the main surface; Codework stays for the full three-panel workspace and is opened with the <code>/codework</code> command from any chat rather than from the sidebar.</p>
+ <section id="skills-interactive">
+ <h2><span class="icon">🎛️</span> Custom Skill Interactive UI</h2>
+ <p>Create skills with interactive elements: buttons, forms, input fields, and custom scripts. Interactive elements run in sandboxed iframes for security.</p>
+
+ <h3>Sandboxed iframes</h3>
+ <p>Skill UIs run in isolated iframe contexts. They cannot access main app memory, settings, or your conversations. Full isolation prevents malicious code execution.</p>
+
+ <h3>Bridge API</h3>
+ <p>Skills communicate with Skales through the Bridge API: <code>skales.rerun()</code> re-executes the skill, <code>skales.navigate()</code> opens pages, <code>skales.send()</code> sends data to the host. Secured via postMessage origin validation.</p>
+
+ <h3>Buttons & Forms</h3>
+ <p>Define buttons with custom labels and click handlers. Build forms with text inputs, dropdowns, checkboxes, and file uploads. Capture user input and send it back to the skill.</p>
+
+ <h3>Scripts & Logic</h3>
+ <p>Skills can include client-side JavaScript for calculations, formatting, or UI state management. Server-side logic runs in the skill's backend with full Skales API access.</p>
+
+ <div class="tip"><strong>💡 Tip:</strong> Interactive UI skills are ideal for custom dashboards, data entry tools, workflow builders, and configuration wizards. See the Skill Development Guide for examples.</div>
+ </section>
+
+ <section id="skill-sharing">
+ <h2><span class="icon">🛠️</span> Skill Sharing & Forking</h2>
+ <p>AI-created Custom Skills (built with Skill AI) can be shared to the Discover feed. Other users can fork (copy) them locally with one click — building a community library of AI-powered skills.</p>
+
+ <h3>How to Share a Skill</h3>
+ <p>Go to <strong>Custom Skills</strong>. AI-generated skills show a <strong>Share to Discover</strong> button (🔗). Click it, review the disclaimer, and confirm. The skill's name, description, and code are posted to the feed — your API keys and personal settings are never included.</p>
+
+ <h3>What Gets Shared vs. What Stays Private</h3>
+ <p><strong>Shared:</strong> Skill name, description, source code, and configuration (category, icon, UI settings).<br><strong>NOT shared:</strong> API keys, personal settings, local data, or any sensitive credentials.</p>
+
+ <h3>How to Fork a Skill</h3>
+ <p>In the Discover feed, skill posts show a <strong>Fork Skill</strong> button. Click it, read the safety disclaimer, and confirm. The skill installs locally in your Custom Skills — ready to enable and use. Forked skills cannot be re-shared (no watermark), but you can edit or delete them anytime.</p>
+
+ <h3>Community Safety</h3>
+ <p>Community skills are created by users and not reviewed by Skales. Only fork skills from agents you trust. Review the code before enabling a forked skill — Skales shows you the full source before you fork.</p>
+ </section>
+
+ <section id="mcp">
+ <h2><span class="icon">🔗</span> MCP Server Support</h2>
+ <p>Connect external tools via <strong>Model Context Protocol</strong>. MCP allows Skales to use tools hosted on external servers.</p>
+ <p>Configure in <strong>Settings &gt; Integrations</strong> when the MCP skill is enabled. 5 built-in templates included.</p>
+
+ <h3>Adding and editing servers</h3>
+ <p>Each row in Settings &gt; Integrations &gt; MCP Servers carries four icons: <strong>Test connection</strong> (test tube), <strong>Edit server</strong> (pencil), <strong>Enable / Disable</strong> (power), <strong>Remove server</strong> (trash). The pencil opens the form pre-filled with the server's name, command, args, and env vars in place so you do not have to retype anything. The dedicated <code>/mcp</code> page still works for the same Edit deep-link.</p>
+
+ <h3>Env vars and tokens</h3>
+ <p>Env variable values default to readable text. Each row has a per-key Show / Hide toggle for screen-sharing situations. Storage is plain JSON on disk anyway (<code>~/.skales-data/mcp-servers.json</code>), so masking only existed to dodge shoulder-surfing.</p>
+
+ <h3>Servers behind an API token</h3>
+ <p>Not every remote server uses sign-in. Most self-hosted ones want a token in a header instead, so an <strong>http</strong> or <strong>sse</strong> server has a <strong>Request headers</strong> editor: add <code>Authorization</code> with a value of <code>Bearer &lt;token&gt;</code>, or whatever header that server asks for. Headers are sent with every request to that server, and they take precedence over anything the sign-in flow would attach.</p>
+ <p>If a server answers <strong>401</strong> and neither uses sign-in nor advertises it, Skales says that plainly and points at the header, rather than sending you to a sign-in that does not exist. If you already set a header and it is still refused, it says that too: the header went out and the server did not accept it.</p>
+
+ <h3>Status badge sanity</h3>
+ <p>A successful Test now promotes the freshly tested client into the live connection pool, so the status badge on the /mcp page flips to "connected (N tools)" on the very next 5 second poll without waiting for a chat turn to lazy-connect. Disabled servers stay disconnected.</p>
+ </section>
+
+ <!-- ===== Chapter: Code ===== -->
+ <section id="ch-code" class="chapter-lead">
+ <div class="lead-kicker">Chapter 3</div>
+ <h2>Code</h2>
+ <p class="lead-intro">Skales Code is a window of its own, pointed at one folder, with a leash you pick when the session starts. It is the same engine as chat, with a repository around it and a review panel at the end.</p>
+
+ <div class="walk">
+ <div class="walk-head"><h3>Walkthrough: a change, read before it is kept</h3><span class="walk-time">3 minutes</span></div>
+ <p class="walk-goal">One small change to a real repository, reviewed line by line, kept and committed, without leaving the window.</p>
+ <ol>
+ <li>
+ <span class="do">Sidebar, <strong>Code</strong>. It opens beside Skales rather than inside it, so the rest of the app keeps working while it does.</span>
+ <span class="then">three ways in: Open project, Clone repo, and the sessions you had open before with their branch and the size of their change.</span>
+ </li>
+ <li>
+ <span class="do">Open a project, and set the mode in the box you type into to <strong>Plan</strong> before you write anything. Then ask:</span>
+ <span class="say">Where is the email field validated, and what would it take to cap it at 64 characters? Do not change anything.</span>
+ <span class="then">reads and greps, no writes at all. In Plan and in Ask, the tools that write are refused rather than discouraged, whatever your global Safety Mode says.</span>
+ </li>
+ <li>
+ <span class="do">Switch the mode to <strong>Code</strong> and ask for the change itself:</span>
+ <span class="say">Do exactly that, and nothing else.</span>
+ <span class="then">a question before each file change, once each, with an always-allow for the ones that get tiring.</span>
+ </li>
+ <li>
+ <span class="do">Click the Edit step to unfold it, then <strong>Review diff</strong>.</span>
+ <span class="then">the panel with every file the session touched, each with its own added and removed counts and its own Keep and Put back.</span>
+ <span class="stuck">you want it undone, <strong>Put back</strong> restores the file and says where the old version came from.</span>
+ </li>
+ <li>
+ <span class="do">Keep the change, then commit and push from the same panel.</span>
+ <span class="then">the status line along the bottom back to idle, with the branch and the new line counts.</span>
+ <span class="stuck">git refuses, you get git's own words back rather than a translation of them.</span>
+ </li>
+ </ol>
+ </div>
+
+ <!-- SHOT code-window-review.png
+ The Skales Code window with a session that has just made a change.
+ Frame: the whole Code window, 1600x1000, dark theme.
+ Must show: the transcript with at least one unfolded Edit step carrying its
+ diff, the artefact panel on the right in Diff view, the mode selector in the
+ composer, and the status line at the bottom with folder, branch and +/- counts.
+ The model name in the header must be the model the session actually runs on.
+ -->
+ <figure class="shot pending">
+ <img src="img/code-window-review.png" alt="The Code window: transcript on the left, the file three ways on the right." loading="lazy" />
+ <div class="slot"><b>Screenshot</b> &middot; The Code window: transcript on the left, the file three ways on the right.</div>
+ <figcaption>The Code window: transcript on the left, the file three ways on the right.</figcaption>
+ </figure>
+
+ <div class="tip"><strong>Before you start:</strong> put the project's own rules in an <code>AGENTS.md</code> at its root. Every session on that project reads it, and it beats your global instructions. See <a href="#chat-code-settings">Settings: Chat and Code</a>.</div>
+
+ <h3>In this chapter</h3>
+ <div class="lead-index">
+ <a href="#code">Skales Code</a>
+ <a href="#chat-code-settings">Settings: Chat &amp; Code</a>
+ <a href="#codework">Skales Codework</a>
+ <a href="#playground">Playground</a>
+ <a href="#devkit">DevKit</a>
+ <a href="#github-int">GitHub</a>
+ <a href="#ftp">FTP/SFTP Deploy</a>
+ </div>
+ </section>
+
+ <section id="code">
+ <h2><span class="icon">💻</span> Skales Code</h2>
+ <p>Skales Code is a window of its own, built for working on a repository. Click <strong>Code</strong> in the sidebar and it opens beside Skales rather than inside it, so you can keep chatting and using everything else while it works. Point it at a folder and say what you want changed.</p>
+
+ <h3>Starting a session</h3>
+ <p>Three ways in: <strong>Open project</strong> picks a folder on this computer, <strong>Clone repo</strong> takes an address (an ssh address included) and clones it into your workspace, and the sessions you had open before are listed underneath with their branch and the size of the change in each. The status line along the bottom always says what is going on: idle or working, which folder, which branch, and how many lines have been added and removed.</p>
+
+ <h3>The four modes, and what each may do</h3>
+ <p>You pick the leash when the session starts, in the box you type into. It is the session that decides, not your global Safety Mode: set the rest of Skales to Unrestricted and a session set to <strong>Code</strong> still asks, because that is what choosing Code meant.</p>
+ <ul>
+ <li><strong>Ask</strong> &mdash; reads and answers. It cannot change anything: the tools that write are refused, not merely discouraged.</li>
+ <li><strong>Plan</strong> &mdash; the same, and the output is a plan. Carrying it out is a separate decision.</li>
+ <li><strong>Code</strong> &mdash; writes, and asks before every file change and every command, once each, with an &ldquo;always allow&rdquo; for the ones that get tiring.</li>
+ <li><strong>Accept edits</strong> &mdash; file changes go through without asking, because choosing this mode <em>is</em> that consent. Commands, pushes and deploys still ask.</li>
+ <li><strong>Auto</strong> &mdash; gets on with it. It still asks about anything that reaches <em>outside</em> the bound folder, anything catastrophic, and anything the scope check flags as more than you asked for.</li>
+ </ul>
+ <div class="warn">
+ <strong>🔒 What no mode lifts</strong> &mdash; Blocked folders stay blocked, every path resolves inside the bound folder, catastrophic commands are refused rather than offered, and a coding session never reads or writes your memory. Auto does not switch any of that off.
+ </div>
+
+ <h3>Reading a session</h3>
+ <p>Every step opens. Click a Read, a Grep, an Edit or a command and it unfolds: exactly what was sent and everything that came back, whole, scrollable, with a copy button on each half, and how long the step took. A change carries its diff on the step that made it, with its own added and removed counts and its own <strong>Keep</strong> and <strong>Revert</strong>. Every path is a link into the panel beside the transcript.</p>
+
+ <h3>Review, commit, pull request</h3>
+ <p><strong>Review diff</strong> opens the panel with every file the session touched. Keep stages a change for the next commit, Put back restores the file and tells you where the old version came from. Commit from the same panel, push, and open a pull request without leaving the window. When git refuses, you get git&rsquo;s own words back.</p>
+
+ <h3>The artefact panel and the picker</h3>
+ <p>The panel beside the transcript shows a file three ways: <strong>Preview</strong>, <strong>Diff</strong> and <strong>Raw</strong>. An HTML file is not shown as source but <em>run</em>, with its own stylesheet and script, so a widget works there the way it will work anywhere. Turn on the picker and click an element in that running page: what to call it in CSS, its own markup and a picture of just that piece go onto the message you are writing.</p>
+
+ <h3>Two things at once: worktrees</h3>
+ <p>Give a second piece of work a name and Skales checks the repository out again into a folder of its own, on a branch of its own, with its own session. Neither run can overwrite the other, and each session says whether it is working, waiting for you, or idle. Removing a parallel checkout tells you when there is uncommitted work in it rather than taking it with the folder, and it never removes the repository itself.</p>
+
+ <h3>Several agents at once</h3>
+ <p>A coding session can send work to sub-agents and run them in parallel. A rail shows what each one is doing and what it has cost, and one button stops all of them.</p>
+
+ <h3>Your terminal</h3>
+ <p>Under the box you type into, a real terminal: your login shell, in the session&rsquo;s folder, with your profile. Not a command field, so <code>vim</code>, <code>top</code>, an interactive prompt, colours, arrow keys and Ctrl-C all behave the way they do anywhere else. Open it with the switch in the title bar or by typing <code>/terminal</code>, drag its top edge to resize it, and open more than one tab if you want.</p>
+ <div class="warn">
+ <strong>🧵 Two shells, never mixed</strong> &mdash; The terminal is <em>yours</em>: your hands, your rights, and the agent can neither see it nor type into it, which is why it needs none of the agent&rsquo;s rules. What the <em>agent</em> runs is the other one, and it goes through every guard above.
+ </div>
+
+ <h3>Commands that do not end</h3>
+ <p>A dev server, a watcher, a long build used to be a choice between a timeout and a blocked session. The agent can now start one in the background: its output appears under the step that started it and grows while you watch, and a strip above the status line lists everything that is running with what it is, how long it has been going, and a stop button. Nothing limits how many run and nothing times them out. Stopping stops the whole tree, so a port really comes free. A session that ends ends its own; so does closing Skales. Your phone can see the same list and press the same stop.</p>
+
+ <h3>Typing: @, drag, and /</h3>
+ <p>Typing <code>@</code> offers the files of the repository, matched on the whole path so a folder name finds them. Drop files onto the box, paste a screenshot, or use the paperclip: video, audio, PDFs and archives attach the way they do in a chat. A slash at the <em>start</em> of a line opens the commands a coding session has: switch mode, open review, commit, open a pull request, stop, start a new session, clear, open the terminal. A slash anywhere else is just a path.</p>
+
+ <h3><code>/clear</code>, and where the work lives</h3>
+ <p><code>/clear</code> starts the conversation over without losing the folder, the branch or your place. Each session also has a scratchpad of its own for the files it needs while it works, kept apart from your workspace and removed with the session.</p>
+
+ <h3>Instructions: AGENTS.md and the order they win in</h3>
+ <p>A coding session reads three things, most specific last: the project&rsquo;s own <code>CLAUDE.md</code> or <code>AGENTS.md</code>, then your global coding instructions, then anything you set for that one session. Put a project&rsquo;s rules in an <code>AGENTS.md</code> at its root and every session on that project follows them. The gear in the Code window edits the global and the per-session boxes; both show an example of what belongs in one &mdash; the language to answer in, your own test command, your commit style, your no-gos &mdash; as a hint, never as content.</p>
+
+ <h3>It hears you while it is working</h3>
+ <p>Type while a session is running and your message joins the run instead of starting a second one on the same transcript, and Skales says so.</p>
+
+ <h3>Code inside a chat</h3>
+ <p>A chat can still be bound to a folder and run in a code mode, and it is the same engine. A chat like that has one button in its header that stops what is running, cleanly, and hands the same session to the Code window &mdash; not a link and not a copy.</p>
+ </section>
+
+ <section id="chat-code-settings">
+ <h2><span class="icon">⌨️</span> Settings: Chat &amp; Code</h2>
+ <p>One tab in Settings for how Skales writes and how it codes.</p>
+ <h3>Standing instructions: SKALES.md and AGENTS.md</h3>
+ <p>Two boxes, two jobs, and the toggle above them says which you are editing.</p>
+ <ul>
+ <li><strong>SKALES.md</strong> is how you want to be <em>answered</em>, everywhere: answer in German, keep it short, never open with a compliment. It travels with every conversation, with tasks and schedules that run while you are away, and with your own agents.</li>
+ <li><strong>AGENTS.md</strong> is how you want work <em>done</em> in a project: the test command, the commit style, the folders nothing may touch. It belongs to a project, at its root, and every coding session on that project reads it.</li>
+ </ul>
+ <p>Both are plain files &mdash; the path is printed under the box, and editing the file in a text editor is the same edit. If it changed on disk while you had unsaved text in the box, Skales says so rather than writing over it. Two places leave your standing instructions out on purpose: an isolated agent, which carries nothing of yours by design, and the calls Skales makes to itself.</p>
+ <h3>Priority</h3>
+ <p>Most specific wins: <strong>the project&rsquo;s own file</strong>, then <strong>your global instructions</strong>, then <strong>this session</strong>. A rule you set for one session beats the same rule set globally, and a project that ships its own conventions beats both.</p>
+ <h3>The rest of the tab</h3>
+ <p><strong>Shell command timeout</strong> sets how long a single command may run before Skales stops it (a command started in the background is not timed at all). <strong>Deep reasoning</strong> asks any model to think a problem through before acting, including models with no reasoning mode of their own. <strong>Code model</strong> runs a strong model for code while your chat stays on your default.</p>
+ </section>
+
+ <section id="codework">
+ <h2><span class="icon">🛠️</span> Skales Codework</h2>
+ <p>An autonomous coding agent built into Skales, with its own file tree, editor and terminal. Select any project folder, describe a task, and watch the AI work. For everyday coding the chat's Code mode (Chat / Code / Edits / Plan / Auto on a bound folder) is now the main surface; Codework stays for the full three-panel workspace and is opened with the <code>/codework</code> command from any chat rather than from the sidebar.</p>
<h3>How to Use</h3>
<ol style="margin: 1rem 0 1rem 1.5rem; color: var(--muted); font-size: 0.875rem;">
@@ -1244,83 +1834,6 @@
<p>Every Codework run is saved as a session. View past sessions on the welcome screen. Delete sessions with the trash icon. Continue a conversation after the agent finishes with the follow-up input.</p>
</section>
- <!-- Organization -->
- <section id="organization">
- <h2><span class="icon">🏢</span> Organization</h2>
- <p>Create multi-agent teams. Build departments, assign agents, and delegate tasks across your AI company.</p>
- <p>How this differs from Group Chat and from asking several agents at once: see <a href="#multi-agent" style="color:var(--accent)">Which multi-agent mode</a>.</p>
-
- <h3>Structure</h3>
- <table>
- <thead><tr><th>Component</th><th>Description</th></tr></thead>
- <tbody>
- <tr><td>CEO</td><td>Top-level agent that routes tasks to the right department</td></tr>
- <tr><td>Departments</td><td>Engineering, Marketing, Operations (customizable)</td></tr>
- <tr><td>Teams</td><td>Groups of agents within a department</td></tr>
- <tr><td>Company Packs</td><td>Export/import your entire org setup as JSON</td></tr>
- </tbody>
- </table>
-
- <h3>Canvas Office</h3>
- <p>A real-time animated canvas visualization of your organization. Agents are rendered as interactive nodes on a 2D canvas with smooth animations, connection lines between team members, and status indicators. The canvas auto-scales to fit your org structure and uses requestAnimationFrame for 60fps rendering.</p>
-
- <h3>Execute Tab with Live Polling</h3>
- <p>Describe a task, select a team, and the CEO agent delegates it to the right agents. The Execute tab now features live step-by-step progress streaming — watch each agent's work unfold in real time with a scrolling log, elapsed timer, and abort button. Results are aggregated and returned when all subtasks complete.</p>
-
- <h3>Projects</h3>
- <p>Save and manage reusable project configurations. Each project stores a name, description, selected team, and default instructions. Load a project to pre-fill the Execute tab instantly. Create, edit, and delete projects from the Projects panel.</p>
-
- <h3>Shared Memory</h3>
- <p>Organization agents share a dedicated memory pool separate from your personal chat memory. Team members can read and write shared context — meeting notes, project decisions, research findings — that persists across execution runs. Manage shared memories from the Organization settings.</p>
-
- <h3>Safe Mode in Organization</h3>
- <p>When Safe Mode is enabled, organization agents are instructed to avoid destructive actions. Instead of sending emails or running shell commands directly, agents prepare the content as files and report what they would have done. You can review and execute manually.</p>
- <table>
- <thead><tr><th>Mode</th><th>Behavior in Organization</th></tr></thead>
- <tbody>
- <tr><td>Safe Mode</td><td>Agents prepare emails as files, describe commands without executing. You review and send manually.</td></tr>
- <tr><td>Unrestricted</td><td>Agents execute all actions including sending emails and running commands without confirmation.</td></tr>
- </tbody>
- </table>
-
- <h3>Email in Organization</h3>
- <p>Organization agents can now send emails as part of their workflows. In Unrestricted mode, the send_email tool executes immediately. In Safe Mode, agents save prepared emails as files for your review.</p>
-
- <div class="warn"><strong>⚠️ Unrestricted Mode</strong> — In Unrestricted mode, organization agents execute all actions including emails and system commands without confirmation. Use with caution.</div>
- </section>
-
- <!-- Computer Use -->
- <section id="computer-use">
- <h2><span class="icon">🖥️</span> Computer Use</h2>
- <p>Skales can control your desktop. Screenshots, mouse clicks, keyboard input, and scrolling.</p>
-
- <h3>Available Actions</h3>
- <div class="card-grid">
- <div class="card"><div class="card-title">Screenshot</div><div class="card-desc">Capture your screen. Appears inline in chat.</div></div>
- <div class="card"><div class="card-title">Click</div><div class="card-desc">Click at specific coordinates on your screen.</div></div>
- <div class="card"><div class="card-title">Type</div><div class="card-desc">Type text into the currently focused application.</div></div>
- <div class="card"><div class="card-title">Scroll</div><div class="card-desc">Scroll up or down in the active window.</div></div>
- </div>
-
- <div class="warn"><strong>⚠️ Safety Mode</strong> — In Safe Mode, every Computer Use action requires your approval before execution.</div>
- </section>
-
- <!-- WordPress 2.0 -->
- <section id="wordpress">
- <h2><span class="icon">🌐</span> WordPress 2.0</h2>
- <p>Skales can build complete WordPress pages with AI. Connect your WordPress site via the Skales Connector Plugin (v1.2.0), then ask the AI to create pages:</p>
- <div class="code-block">"Create a landing page for my business with hero, features, pricing, and contact sections"</div>
- <p>The AI uses Elementor's Flexbox Container format with professional design templates. It can also search the web for current content before building pages.</p>
- <h3>Capabilities</h3>
- <div class="card-grid">
- <div class="card"><div class="card-title">15 Elementor Templates</div><div class="card-desc">Hero, Features, Testimonials, Pricing, CTA, Footer, and more.</div></div>
- <div class="card"><div class="card-title">10 Gutenberg Patterns</div><div class="card-desc">Block patterns for the default WordPress editor.</div></div>
- <div class="card"><div class="card-title">Selective Skill Injection</div><div class="card-desc">Reduces prompt from 96KB to ~13KB by injecting only relevant design sections.</div></div>
- <div class="card"><div class="card-title">Collision Detection</div><div class="card-desc">Plugin v1.2.0 prevents accidental page overwrites.</div></div>
- </div>
- </section>
-
- <!-- Playground -->
<section id="playground">
<h2><span class="icon">🎮</span> Playground <span class="badge badge-new">Beta · v9.2.5</span></h2>
<p>Playground is your personal AI workspace. It starts with a deep interview to understand your work style, goals, and design preferences. Based on your answers, Playground suggests personalized Spaces — interactive mini-apps built specifically for you.</p>
@@ -1335,15 +1848,6 @@
</div>
</section>
- <!-- Download File -->
- <section id="download-file">
- <h2><span class="icon">📥</span> Download File</h2>
- <p>The download_file tool lets you download files from any URL:</p>
- <div class="code-block">"Download the PDF from https://example.com/report.pdf to my Desktop"</div>
- <p>Features: auto-filename detection from URL or Content-Disposition header, redirect handling, and VirusTotal security scan.</p>
- </section>
-
- <!-- DevKit -->
<section id="devkit">
<h2><span class="icon">🧑‍💻</span> DevKit</h2>
<p>Developer tools for power users. Requires a <code>devkit/</code> folder in your Skales installation directory with a <code>devkit.json</code> config file.</p>
@@ -1356,110 +1860,274 @@
</div>
</section>
- <!-- MCP Servers -->
- <section id="mcp">
- <h2><span class="icon">🔗</span> MCP Server Support</h2>
- <p>Connect external tools via <strong>Model Context Protocol</strong>. MCP allows Skales to use tools hosted on external servers.</p>
- <p>Configure in <strong>Settings &gt; Integrations</strong> when the MCP skill is enabled. 5 built-in templates included.</p>
+ <section id="github-int">
+ <h2><span class="icon">🐙</span> GitHub</h2>
+ <p>List repos, create issues, search code. Requires a GitHub Personal Access Token. Configure in <strong>Settings > Integrations</strong>.</p>
+ </section>
- <h3>Adding and editing servers</h3>
- <p>Each row in Settings &gt; Integrations &gt; MCP Servers carries four icons: <strong>Test connection</strong> (test tube), <strong>Edit server</strong> (pencil), <strong>Enable / Disable</strong> (power), <strong>Remove server</strong> (trash). The pencil opens the form pre-filled with the server's name, command, args, and env vars in place so you do not have to retype anything. The dedicated <code>/mcp</code> page still works for the same Edit deep-link.</p>
+ <section id="ftp">
+ <h2><span class="icon">🚀</span> FTP/SFTP Deploy</h2>
+ <p>Central server profile management. Deploy Lio AI projects with one click to your hosting.</p>
- <h3>Env vars and tokens</h3>
- <p>Env variable values default to readable text. Each row has a per-key Show / Hide toggle for screen-sharing situations. Storage is plain JSON on disk anyway (<code>~/.skales-data/mcp-servers.json</code>), so masking only existed to dodge shoulder-surfing.</p>
+ <h3>Server Profiles</h3>
+ <p>Store FTP/SFTP connection details securely in <strong>Settings → Deploy</strong>. Encrypt credentials locally using your master password. Since v12.4.0 each profile carries its protocol explicitly &mdash; FTP, FTPS (explicit TLS, switches on automatically when the server requires it) or SFTP. On the first successful SFTP test or publish, Skales pins the server&rsquo;s SSH host-key fingerprint to the profile; if the key ever changes, the next upload is refused. Profiles can also be bound to a single agent, so an isolated agent publishes only through its own space (v12.3.5).</p>
- <h3>Servers behind an API token</h3>
- <p>Not every remote server uses sign-in. Most self-hosted ones want a token in a header instead, so an <strong>http</strong> or <strong>sse</strong> server has a <strong>Request headers</strong> editor: add <code>Authorization</code> with a value of <code>Bearer &lt;token&gt;</code>, or whatever header that server asks for. Headers are sent with every request to that server, and they take precedence over anything the sign-in flow would attach.</p>
- <p>If a server answers <strong>401</strong> and neither uses sign-in nor advertises it, Skales says that plainly and points at the header, rather than sending you to a sign-in that does not exist. If you already set a header and it is still refused, it says that too: the header went out and the server did not accept it.</p>
+ <h3>One-Click Deploy</h3>
+ <p>Build your Lio AI project and deploy directly to a server. Skales handles file transfers and confirms deployment success.</p>
- <h3>Status badge sanity</h3>
- <p>A successful Test now promotes the freshly tested client into the live connection pool, so the status badge on the /mcp page flips to "connected (N tools)" on the very next 5 second poll without waiting for a chat turn to lazy-connect. Disabled servers stay disconnected.</p>
+ <h3>Live Preview</h3>
+ <p>After deployment, quickly open your deployed project in the browser to verify it's running correctly.</p>
</section>
- <!-- Migration Importer -->
- <section id="migration">
- <h2><span class="icon">🔄</span> Migration Importer</h2>
- <p>Import conversation history from other AI tools.</p>
- <table>
- <thead><tr><th>Source</th><th>Format</th></tr></thead>
- <tbody>
- <tr><td>ChatGPT</td><td>conversations.json from data export</td></tr>
- <tr><td>Claude</td><td>JSON export</td></tr>
- <tr><td>Copilot</td><td>JSON export</td></tr>
- <tr><td>Gemini</td><td>JSON export</td></tr>
- <tr><td>Markdown</td><td>Any .md file</td></tr>
- <tr><td>Generic JSON</td><td>Array of message objects</td></tr>
- </tbody>
- </table>
- <p>Access via <strong>Settings > Import from Another Tool</strong>.</p>
+ <!-- ===== Chapter: Studio and Flow ===== -->
+ <section id="ch-studio" class="chapter-lead">
+ <div class="lead-kicker">Chapter 4</div>
+ <h2>Studio and Flow</h2>
+ <p class="lead-intro">Studio is the one-shot side: describe a picture, a clip, a voice line, a piece of music, and get it. Flow is the other side: one brief that keeps being worked on, with every turn sealed so you can go back to any of them.</p>
+
+ <div class="walk">
+ <div class="walk-head"><h3>Walkthrough: a picture, a headline, a shot</h3><span class="walk-time">3 minutes</span></div>
+ <p class="walk-goal">Three outputs, one from each of the three ways Studio makes things: a model, a renderer with no AI in it at all, and a conversation.</p>
+ <ol>
+ <li>
+ <span class="do">Sidebar, <strong>Studio</strong>, the <strong>Image</strong> tab. Describe something specific rather than something impressive:</span>
+ <span class="say">A flat vector icon of a green lizard on a dark background, no text, centred.</span>
+ <span class="then">the picture in the preview and the same picture already in your Gallery, with the prompt kept beside it.</span>
+ </li>
+ <li>
+ <span class="do">Open the <strong>Type</strong> tab, put in a short line, and pick the <strong>Neon</strong> motion preset.</span>
+ <span class="say">Ship it.</span>
+ <span class="then">the animation running in the live preview immediately. Nothing was generated and no key was used: Type is a timeline engine, not a model.</span>
+ <span class="stuck">you want it over other footage, set the background to <strong>Transparent</strong> and the export becomes an alpha WebM instead of an MP4.</span>
+ </li>
+ <li>
+ <span class="do">Open <strong>Flow</strong> and choose <strong>Film</strong>. Pick the camera move <em>before</em> you write the brief, and pick exactly one.</span>
+ <span class="then">the brief box, with the move you chose held next to it.</span>
+ </li>
+ <li>
+ <span class="do">Write the brief:</span>
+ <span class="say">A rain soaked street at night, one neon sign, nobody in frame.</span>
+ <span class="then">a clip, generated through whichever of the three routes you have set up. With none of them set up, the chip says which key is missing and where it goes, and keeps your camera move.</span>
+ </li>
+ <li>
+ <span class="do">Answer the result instead of starting over. Follow-ups are takes:</span>
+ <span class="say">Same shot, tighter, and at dawn.</span>
+ <span class="then">a new take saved beside the earlier one, with everything you did not change kept.</span>
+ </li>
+ </ol>
+ </div>
+
+ <!-- SHOT studio-type-preview.png
+ Studio, the Type tab, with a motion preset selected and the preview running.
+ Frame: whole app window, 1440x900, dark theme.
+ Must show: the preset row, the live preview mid-animation, and the controls
+ for font, background, aspect and duration. A frame where the letters are
+ part-way through the animation reads far better than the finished state.
+ -->
+ <figure class="shot pending">
+ <img src="img/studio-type-preview.png" alt="Type: fourteen motion presets, a live preview, and no model behind any of it." loading="lazy" />
+ <div class="slot"><b>Screenshot</b> &middot; Type: fourteen motion presets, a live preview, and no model behind any of it.</div>
+ <figcaption>Type: fourteen motion presets, a live preview, and no model behind any of it.</figcaption>
+ </figure>
+
+ <!-- SHOT flow-film-moves.png
+ Flow, Film mode, the camera move picker open.
+ Frame: whole app window, 1440x900, dark theme.
+ Must show: the moves grouped by family (zoom, dolly, crane, pan, orbit, rig,
+ aerial, lens), one selected, and the brief box still empty. Do not crop the
+ group headings away - the grouping is the point.
+ -->
+ <figure class="shot pending">
+ <img src="img/flow-film-moves.png" alt="Film: the camera move is the first decision, and there is only ever one." loading="lazy" />
+ <div class="slot"><b>Screenshot</b> &middot; Film: the camera move is the first decision, and there is only ever one.</div>
+ <figcaption>Film: the camera move is the first decision, and there is only ever one.</figcaption>
+ </figure>
+
+ <h3>In this chapter</h3>
+ <div class="lead-index">
+ <a href="#studio">Skales Studio</a>
+ <a href="#flow">Flow</a>
+ <a href="#images">Image & Video Generation</a>
+ <a href="#templates">Templates</a>
+ <a href="#wordpress">WordPress 2.0</a>
+ </div>
</section>
- <!-- Always-On -->
- <section id="always-on">
- <h2><span class="icon">⏰</span> Always-On Agent <span class="badge badge-beta">Beta</span></h2>
- <p>Schedule recurring tasks using cron expressions. Skales runs them automatically in the background, even when you're not actively chatting.</p>
+ <section id="studio">
+ <h2><span class="icon">🎨</span> Skales Studio</h2>
+ <p>An all-in-one AI creative suite built into Skales. Generate images, videos, voice audio, and music — all from a single interface. Every output is saved to your Gallery and can be reused at any time.</p>
- <h3>Built-in Jobs</h3>
- <table>
- <thead><tr><th>Job</th><th>Schedule</th><th>Description</th></tr></thead>
- <tbody>
- <tr><td>Identity Maintenance</td><td>Daily</td><td>Updates your Skales identity file with new learnings, memories, and preferences.</td></tr>
- <tr><td>Morning Briefing</td><td>Configurable</td><td>Daily summary of tasks, calendar, and news. Delivered to Telegram if configured.</td></tr>
- </tbody>
- </table>
+ <h3>Image Generation</h3>
+ <p>Describe what you want and choose your provider. Skales Visuals is the built-in renderer. For higher resolution or photorealism, connect Google (Nano Banana Pro, Imagen 4), OpenAI (GPT Image 1), Replicate (Flux, SDXL), HuggingFace, or a local ComfyUI or Stable Diffusion WebUI instance. Export as PNG. The full list per service is under <a href="#images">Image and Video Generation</a>.</p>
- <h3>Custom Schedules</h3>
- <p>Add any cron job in Settings → Always-On. Examples:</p>
- <pre><code>0 9 * * 1-5 # Weekdays at 9 AM
-0 */2 * * * # Every 2 hours
-0 20 * * * # Every day at 8 PM</code></pre>
+ <h3>Video Creation</h3>
+ <p>Describe a motion graphic in plain language — counters, text animations, infographics, slideshows, social posts. Skales Studio renders it instantly in the live preview. Iterate with follow-up instructions. When you're happy with the result, export as MP4 using the built-in FFmpeg renderer. Categories: Text Animation, Infographic, Data Visualization, Logo Intro, Slideshow, Social Post, Counter/Stats.</p>
+
+ <h3>Type</h3>
+ <p>Open <strong>Sidebar → Studio → Type</strong> to turn a line of text into an animated, looping video (kinetic typography), with no AI and no setup. The headline is a set of <strong>14 Motion presets</strong> driven by a real timeline engine, with custom easing, per-letter staggers and depth: Cascade, Drop, Pop, Bounce, Slide, Reveal, Flip 3D, Spin, Wave, Breathe, Glitch, Neon, Shine, Typewriter. Pick one and it just works, there is nothing to configure. Below them are 18 simpler presets, including real 3D ones: Fade, Rise, Slide, Typewriter, Word cascade, Letter pop, Zoom in, Zoom blast, Blur focus, 3D flip, 3D swing, Cube roll, Depth dive, Wave, Neon, Glitch, Reveal, Expand. Set the font, weight, text color, background (presets including a Skales-X theme and a Transparent option), aspect (9:16, 16:9, 1:1, 4:5), duration, font size, and a Loop toggle. Watch the live preview, then Export. A transparent background exports an alpha WebM (VP9) you can lay over other footage; otherwise you get an MP4. It uses the same HTML-to-frames-to-FFmpeg pipeline as Studio's other video, so every frame is exact.</p>
+
+ <h3>Voice / TTS</h3>
+ <p>Paste or type a script and generate speech. Skales auto-detects your available TTS provider: Local (OS voices), ElevenLabs, Azure Neural TTS, Groq TTS, OpenAI TTS, or Google TTS. Preview in-app, then download as MP3.</p>
+
+ <h3>Music Generation</h3>
+ <p>Generate AI music via Meta MusicGen (HuggingFace). Select genre, mood, and duration. Preview and download the result directly from the Studio interface.</p>
+
+ <h3>Gallery</h3>
+ <p>Every Studio output — images, videos, audio — is automatically saved to your Gallery. Filter by type, search by prompt, or browse the masonry grid. Click <strong>Reuse</strong> on any entry to jump back to the generating tab with the prompt and preview restored so you can continue iterating.</p>
+
+ <h3>Brand Kit</h3>
+ <p>Configure your brand once in <strong>Studio → Brand Kit</strong>: logo, primary colors, fonts, tagline, and tone of voice. Enable the <em>Use Brand Kit</em> checkbox in Image or Video generation to automatically inject brand context into every prompt.</p>
+
+ <div class="tip"><strong>💡 Tip:</strong> All Studio files are stored under <code>~/.skales-data/studio/</code>. Images go to <code>gallery/</code>, videos to <code>videos/</code>. Filenames are prefixed with <code>skales_studio_</code>.</div>
</section>
- <!-- Dashboard -->
- <section id="dashboard">
- <h2><span class="icon">📊</span> Dashboard</h2>
- <p>A customizable home screen with status cards and optional widgets.</p>
+ <section id="flow">
+ <h2><span class="icon">🌊</span> Flow</h2>
+ <p>Flow is Studio&rsquo;s conversational design workspace: one brief, and it keeps working on it with you instead of returning a single result. Nine modes, and Flow picks the one that fits what you asked unless you say otherwise: <strong>deck</strong>, <strong>prototype</strong>, <strong>wireframe</strong>, <strong>mobile</strong> mockup, print <strong>document</strong>, <strong>image</strong>, <strong>video</strong>, <strong>film</strong> and <strong>motion</strong> graphic.</p>
+ <h3>Film: one shot, one camera move</h3>
+ <p>Film makes a single clip with a single deliberate camera move, and the move is what you pick first &mdash; before you write a word of the brief. Fifty-one of them, grouped by what they are: zoom, dolly, crane, pan, orbit, rig, aerial and lens. One move per clip, and there is no way to pick two: mixing camera moves in one generated shot is exactly what makes generated footage look generated.</p>
+ <p>Where the clip comes from, in this order:</p>
+ <ol>
+ <li><strong>Higgsfield</strong>, if you have connected it as an MCP server under Settings. It executes a camera preset as a preset rather than as words, so it gives the best result for this mode.</li>
+ <li><strong>The video APIs under Settings &rsaquo; Skales Studio</strong> &mdash; Kling, Runway, fal, Google Veo, Replicate or OpenRouter. None of them takes a camera-move parameter, so the move you picked steers the prompt instead. This is the normal path and it works well.</li>
+ <li><strong>A Hugging Face Space you have activated</strong>, as the budget route: free or nearly so, on a shared queue, and slower.</li>
+ </ol>
+ <p>If none of the three is set up, the chip stays where it is and tells you which key is missing and where it goes. It keeps the camera move you picked either way. Follow-up messages are takes: &ldquo;tighter&rdquo;, &ldquo;try it as a crane up&rdquo;, &ldquo;same shot at night&rdquo; keep everything you did not change and save the result beside the earlier takes.</p>
+ <p>On the phone, Film works the same way with the same moves, and generates through the video key on the phone (fal.ai under Integrations, or an OpenRouter key under Provider). With no key it says so rather than producing an animation and calling it a film.</p>
+ <h3>Nothing you made is gone</h3>
+ <p>Every turn seals a version of the whole project, so you can go back to any of them &mdash; and the rollback is itself sealed first, which is what keeps going back reversible. Projects can be archived (reversible, keeps everything) or deleted (the folder moves to a trash folder next to your projects).</p>
+ <h3>Brand Kit and style packs</h3>
+ <p>Your Brand Kit &mdash; logo, colours, fonts, tone &mdash; applies to a Flow project, and a style pack can be pinned next to it. Your brief always wins on content.</p>
+ <h3>Handing it to Code</h3>
+ <p>A design in Studio or Flow can be handed to the coding session that will build it, so the thing you approved is what gets built.</p>
+ </section>
- <h3>Status Cards</h3>
- <p>Always visible: connected providers, API status, active bots (Telegram, WhatsApp, Discord), theme selector, recent sessions.</p>
+ <section id="images">
+ <h2><span class="icon">🎨</span> Image & Video Generation</h2>
+ <p>Which models you can reach depends on which keys you have entered under <strong>Settings &rsaquo; Skales Studio</strong>. The lists below are what Skales offers per service; the picker only shows the ones you have a key for.</p>
- <h3>Optional Widgets</h3>
- <div class="card-grid">
- <div class="card"><div class="card-title">🗓 Calendar</div><div class="card-desc">Upcoming events from your connected calendar.</div></div>
- <div class="card"><div class="card-title">🌤 Weather</div><div class="card-desc">Current conditions and forecast for your location.</div></div>
- <div class="card"><div class="card-title">🦎 Buddy</div><div class="card-desc">Quick access to your Desktop Buddy companion.</div></div>
- <div class="card"><div class="card-title">📧 Email</div><div class="card-desc">Unread email summary from your connected account.</div></div>
- <div class="card"><div class="card-title">✅ Tasks</div><div class="card-desc">Active Autopilot tasks and their status.</div></div>
- <div class="card"><div class="card-title">📋 Plan</div><div class="card-desc">Today's AI-generated daily plan.</div></div>
- <div class="card"><div class="card-title">📈 Stats</div><div class="card-desc">Usage statistics, token counts, and session history.</div></div>
- </div>
- <p style="margin-top:0.75rem;">Enable or disable widgets in <strong>Settings → Dashboard</strong>.</p>
+ <h3>Pictures</h3>
+ <ul>
+ <li><strong>Google.</strong> Nano Banana Pro (Gemini 3 Pro Image), Nano Banana 2 (Gemini 3.1 Flash Image), Gemini Flash Image, Imagen 4 and Imagen 4 Fast.</li>
+ <li><strong>OpenAI.</strong> GPT Image 1, and DALL-E 3 as the older one.</li>
+ <li><strong>Replicate.</strong> Flux Schnell, Flux 1.1 Pro, Flux 1.1 Pro Ultra and Stable Diffusion XL.</li>
+ <li><strong>HuggingFace.</strong> Flux Schnell (free), Flux Dev, SDXL Base, SD 3.5 Large and SDXL Lightning.</li>
+ <li><strong>On your own machine.</strong> A running <strong>ComfyUI</strong> or <strong>Stable Diffusion WebUI</strong>. No key and no account: Skales talks to the server you already have. A GPU is what makes it bearable rather than what makes it work.</li>
+ </ul>
+ <p>Style presets sit next to the prompt rather than inside it: photorealistic, illustration, 3D render, anime, cinematic, or none. Aspect is 1:1, 16:9, 9:16 or 4:5.</p>
- <h3>In-App Notifications</h3>
- <p>Toast notifications appear in-app for important events: task completions, message arrivals, calendar reminders, and system alerts. Notifications can be accessed in the dedicated Notification Center for history and filtering.</p>
+ <h3>Video</h3>
+ <ul>
+ <li><strong>Google Veo.</strong> Veo 3.1, Veo 3.1 Fast, and Veo 3 as the older tier.</li>
+ <li><strong>Kling.</strong> v2, v1.6 and v1.5.</li>
+ <li><strong>Runway</strong>, <strong>Replicate</strong> and <strong>fal</strong>.</li>
+ <li><strong>Through a gateway.</strong> OpenRouter video, and Skales IQ video on the trial.</li>
+ </ul>
+
+ <div class="tip"><strong>Not every video needs a model.</strong> Studio's own renderer makes motion graphics, counters, slideshows and kinetic typography with no generation and no key at all, frame by frame through FFmpeg. See <a href="#studio">Skales Studio</a>, and <a href="#studio">Type</a> for the text one.</div>
</section>
- <!-- Desktop Buddy -->
- <section id="buddy">
- <h2><span class="icon">🦎</span> Desktop Buddy</h2>
- <p>A floating AI companion that lives on your desktop. Always accessible, even when Skales is minimized.</p>
+ <section id="templates">
+ <h2><span class="icon">🗂️</span> Templates</h2>
+ <p>37 pre-built prompt templates spanning every Skales module. Click any template to open the target module with the prompt already filled in — no copy-pasting required.</p>
- <h3>A full agent (v11.3.2 &ldquo;Re-Buddy&rdquo;)</h3>
- <p>The buddy runs the complete multi-step agent loop &mdash; with the same generous working budget as the WhatsApp/Telegram channels. Ask it to clean a folder, send a mail, check your calendar: it works until the task is done, and the speech bubble shows <strong>live progress lines</strong> as each step finishes. It speaks with your configured persona, in your language, recalls what it knows about you, and keeps its <strong>own conversation thread</strong> &mdash; &ldquo;Open Chat&rdquo; jumps straight to it.</p>
+ <h3>Template Categories</h3>
+ <table>
+ <thead><tr><th>Category</th><th>Examples</th></tr></thead>
+ <tbody>
+ <tr><td>Chat</td><td>Research briefing, email rewrite, document summary</td></tr>
+ <tr><td>Codework</td><td>Refactor for readability, add unit tests, migrate to TypeScript</td></tr>
+ <tr><td>Organization</td><td>Marketing campaign, competitive analysis, product spec</td></tr>
+ <tr><td>Lio AI</td><td>Landing page, dashboard component, data visualizer</td></tr>
+ <tr><td>Browser</td><td>Price comparison, news digest, form auto-fill</td></tr>
+ <tr><td>Planner</td><td>Weekly agenda, project breakdown, task prioritizer</td></tr>
+ <tr><td>Studio</td><td>Brand intro video, podcast cover art, social post graphic</td></tr>
+ </tbody>
+ </table>
- <h3>Skins &amp; custom pixel pets</h3>
- <p>Three classic WebM skins (Skales, Bubbles, Capy) in <strong>Settings → General → Buddy Skin</strong>. Below them: <strong>Custom pixel skins</strong> &mdash; animated pixel pets in the open <a href="https://petdex.dev" target="_blank" rel="noopener">Petdex</a> sprite format. Three Skales originals ship built in, any pet from the petdex.dev gallery imports with one paste (URL or name), and the <strong>&ldquo;+&rdquo; card opens the pet creator</strong>: pick shape, color, eyes, ears, tail and an accessory, watch the live preview, save &mdash; rendered locally in seconds, no image model. You can also just tell Skales in chat: <em>&ldquo;make me a purple octopus buddy&rdquo;</em>. The pixel pet reacts to your agent: it inspects while Skales thinks, waits during approvals, slumps on errors, jumps when the task lands.</p>
+ <h3>Template Maker</h3>
+ <p>Build your own templates with the AI-guided interview wizard. Describe your use case, and the Template Maker generates a reusable prompt with the right structure, placeholders, and target module. Custom templates are stored locally and can be shared via the Discover Feed.</p>
- <h3>Approve / Decline &mdash; and it keeps going</h3>
- <p>When Skales needs confirmation before an action (in Safe Mode), the Buddy shows approve/decline buttons in the bubble. Since v11.3.2, approving <strong>continues the task</strong> with the remaining step budget instead of ending the turn &mdash; multi-step jobs ask again when the next gated step comes up.</p>
+ <div class="tip"><strong>💡 Tip:</strong> Templates shared to Discover can be forked by other users — a great way to share your best workflows with the community.</div>
+ </section>
- <h3>Friend Mode</h3>
- <p>When Friend Mode is enabled, the Buddy proactively reaches out — checking in, celebrating wins, or sending nudges based on your activity. Messages can be delivered via Chat, Telegram, or WhatsApp.</p>
+ <section id="wordpress">
+ <h2><span class="icon">🌐</span> WordPress 2.0</h2>
+ <p>Skales can build complete WordPress pages with AI. Connect your WordPress site via the Skales Connector Plugin (v1.2.0), then ask the AI to create pages:</p>
+ <div class="code-block">"Create a landing page for my business with hero, features, pricing, and contact sections"</div>
+ <p>The AI uses Elementor's Flexbox Container format with professional design templates. It can also search the web for current content before building pages.</p>
+ <h3>Capabilities</h3>
+ <div class="card-grid">
+ <div class="card"><div class="card-title">15 Elementor Templates</div><div class="card-desc">Hero, Features, Testimonials, Pricing, CTA, Footer, and more.</div></div>
+ <div class="card"><div class="card-title">10 Gutenberg Patterns</div><div class="card-desc">Block patterns for the default WordPress editor.</div></div>
+ <div class="card"><div class="card-title">Selective Skill Injection</div><div class="card-desc">Reduces prompt from 96KB to ~13KB by injecting only relevant design sections.</div></div>
+ <div class="card"><div class="card-title">Collision Detection</div><div class="card-desc">Plugin v1.2.0 prevents accidental page overwrites.</div></div>
+ </div>
+ </section>
- <div class="tip"><strong>💡 Tip:</strong> Friend Mode works independently of Autopilot. You don't need Autopilot enabled to receive proactive messages.</div>
+ <!-- ===== Chapter: Iris and Voice ===== -->
+ <section id="ch-iris" class="chapter-lead">
+ <div class="lead-kicker">Chapter 5</div>
+ <h2>Iris and Voice</h2>
+ <p class="lead-intro">Same Skales, same conversation file, same tools and the same permissions. Only the way in is different: you talk, it answers out loud, and a ring of particles shows you what just happened.</p>
+
+ <div class="walk">
+ <div class="walk-head"><h3>Walkthrough: a conversation with no keyboard in it</h3><span class="walk-time">3 minutes</span></div>
+ <p class="walk-goal">One spoken exchange, one thing to look at, one timer, all without touching the keyboard after the first key.</p>
+ <ol>
+ <li>
+ <span class="do">Sidebar, <strong>Iris Orbit</strong>. Press <strong>Space</strong> and speak.</span>
+ <span class="say">What is on my plan for today?</span>
+ <span class="then">the eye open and the ring pulsing with your microphone level while you talk, then a spoken answer. You press Space once: after the first turn the ear opens again by itself at the end of every answer.</span>
+ <span class="stuck">nothing was understood, the line under the eye says so and says why. It never fails silently.</span>
+ </li>
+ <li>
+ <span class="do">Ask for something worth looking at rather than only hearing:</span>
+ <span class="say">Search the web for what is new in local AI this week.</span>
+ <span class="then">the ring leave the eye and become the border of a panel holding the results as cards with their sources. You did not ask for the panel and there is no button for it: it follows from what the answer did.</span>
+ </li>
+ <li>
+ <span class="do">Ask for a shape. The vocabulary is the Lucide icon catalogue, in all twelve interface languages.</span>
+ <span class="say">Morph into a coffee cup.</span>
+ <span class="then">the particles rearrange. A word with no shape behind it is not an error; they simply stay as they are.</span>
+ </li>
+ <li>
+ <span class="do">Start a timer out loud.</span>
+ <span class="say">Twenty five minutes of focus.</span>
+ <span class="then">the ring become the countdown digits themselves, and a shockwave when it goes off.</span>
+ </li>
+ <li>
+ <span class="do">Right-click the window and open the first entry, <strong>What can I say?</strong></span>
+ <span class="then">a list of sentences that actually do something, with a real example each. Asking her the same question out loud gets the same list.</span>
+ </li>
+ </ol>
+ </div>
+
+ <!-- SHOT iris-orbit-panel.png
+ Iris Orbit with an orbit open - the web search one is the most legible.
+ Frame: the whole Iris window, at its normal size, dark background.
+ Must show: the ring as the panel border, result cards with their sources
+ inside it, and the one line of text under the eye. Do not screenshot the
+ resting eye for this one; the resting state is already shown by the chapter.
+ -->
+ <figure class="shot pending">
+ <img src="img/iris-orbit-panel.png" alt="When an answer is worth seeing, the ring becomes the panel around it." loading="lazy" />
+ <div class="slot"><b>Screenshot</b> &middot; When an answer is worth seeing, the ring becomes the panel around it.</div>
+ <figcaption>When an answer is worth seeing, the ring becomes the panel around it.</figcaption>
+ </figure>
+
+ <div class="warn"><strong>From a phone browser:</strong> Iris draws, but she will not hear you. A browser only hands out the microphone over HTTPS or on localhost, so a plain <code>http://100.x.x.x</code> address is refused silently by the browser rather than by Skales. See <a href="#iris">Reaching Iris from a phone browser</a>.</div>
+
+ <h3>In this chapter</h3>
+ <div class="lead-index">
+ <a href="#iris">Iris Orbit</a>
+ <a href="#voice">Live Voice</a>
+ <a href="#own-speech">Your own speech server</a>
+ <a href="#buddy">Desktop Buddy</a>
+ <a href="#aipointer">AIPointer ⦿</a>
+ </div>
</section>
- <!-- Iris Orbit -->
<section id="iris">
<h2><span class="icon">👁</span> Iris Orbit <span class="badge badge-beta">Beta v1.0</span></h2>
<p>A window with no toolbar, no composer and no message list: a particle eye, and one line of text under it. You talk, Skales answers out loud, and the particles do something that matches what just happened. It is the same Skales underneath - the same conversation file, the same model, the same tools, the same permissions. Only the way in is different.</p>
@@ -1538,7 +2206,6 @@
<p>Nowhere new. A voice conversation is an ordinary Skales session, in the same place as every other one, and it shows up in <strong>History</strong> like the rest. Open one in the chat and it is a normal chat - the voice surface is a way of talking to a session, not a separate kind of session.</p>
</section>
- <!-- Live Voice -->
<section id="voice">
<h2><span class="icon">🎤</span> Live Voice <span class="badge badge-beta">Beta</span></h2>
<p>Full-duplex voice conversation. Speak naturally and Skales responds with synthesized speech.</p>
@@ -1553,275 +2220,823 @@
<p>Your Mac already has dozens of voices installed, the premium ones included, and they cost nothing and never leave your own devices. The paired Skales app (2.5.6 and newer) can use them: pick <strong>Voices from your Mac</strong> under Voice in the app, choose one from the list your computer reports, and this machine speaks for the phone over the pairing connection. It is offered only while this computer is awake and reachable in Remote mode; if it goes away mid-sentence the phone falls back to its own voice rather than going quiet. The same is available locally at <code>/api/tts/say</code> (GET lists the voices, POST returns audio). A computer that is not a Mac says so instead of reporting an empty voice list.</p>
</section>
- <!-- Agent Swarm -->
<section id="own-speech">
<h2><span class="icon">🗣️</span> Your own speech server</h2>
<p>Reading aloud and dictation do not have to go through a provider. Under <strong>Settings</strong> you can point Skales at your own endpoint for text-to-speech and for speech-to-text, so the voice side runs wherever you decide &mdash; a machine on your network, a container, a service you host. Everything that speaks or listens in Skales then uses it: the chat, the Code window&rsquo;s dictation, voice notes.</p>
</section>
- <section id="swarm">
- <h2><span class="icon">🐝</span> Agent Swarm <span class="badge badge-beta">Beta</span></h2>
- <p>Run multiple Skales instances on your network and have them work as one. Peers are discovered automatically via <strong>mDNS</strong>, or added manually by <strong>IP:port</strong> (perfect for Tailscale) &mdash; manual peers survive restarts and are health-checked every 30 seconds.</p>
- <p>Delegate from any chat: <code>/swarm &lt;task&gt;</code> sends to the best free device, <code>/swarm @name &lt;task&gt;</code> targets a specific one, and an optional mode prefix sets how the task runs on the receiver &mdash; <code>code:</code> (coding agent), <code>plan:</code> (read-only plan), <code>auto:</code> (fully autonomous). The Swarm page offers the same as a form, plus the shared task history with live status. Results return to the chat you sent from and to Notifications.</p>
- <p><strong>Security:</strong> receiving devices must opt in (&ldquo;Accept delegated tasks&rdquo;) and both devices need the same <code>SKALES_AGENT_SECRET</code> environment variable. Delegated tasks appear on the receiver&rsquo;s Tasks page with a 🐝 badge naming the sender.</p>
- </section>
+ <section id="buddy">
+ <h2><span class="icon">🦎</span> Desktop Buddy</h2>
+ <p>A floating AI companion that lives on your desktop. Always accessible, even when Skales is minimized.</p>
- <!-- Themes -->
- <section id="themes">
- <h2><span class="icon">🎨</span> Themes</h2>
- <table>
- <thead><tr><th>Theme</th><th>Mode</th><th>Layout</th><th>Description</th></tr></thead>
- <tbody>
- <tr><td>Skales Modern (default)</td><td>Dark / Light</td><td>Sidebar</td><td>Navy + emerald. The new default experience.</td></tr>
- <tr><td>Classic</td><td>Dark / Light</td><td>Sidebar</td><td>Clean, professional. The original Skales look.</td></tr>
- <tr><td>Obsidian</td><td>Dark</td><td>Top Nav</td><td>Deep black, wide layout — great for large screens.</td></tr>
- <tr><td>Snowfield</td><td>Light</td><td>Icon Rail</td><td>Minimal icon sidebar, high contrast white.</td></tr>
- <tr><td>Neon</td><td>Dark</td><td>Icon Rail</td><td>Vibrant accent colors, compact icon-only sidebar.</td></tr>
- </tbody>
- </table>
- <p style="margin-top:0.75rem;">Change themes on the Dashboard or in Settings → Appearance.</p>
- </section>
+ <h3>A full agent (v11.3.2 &ldquo;Re-Buddy&rdquo;)</h3>
+ <p>The buddy runs the complete multi-step agent loop &mdash; with the same generous working budget as the WhatsApp/Telegram channels. Ask it to clean a folder, send a mail, check your calendar: it works until the task is done, and the speech bubble shows <strong>live progress lines</strong> as each step finishes. It speaks with your configured persona, in your language, recalls what it knows about you, and keeps its <strong>own conversation thread</strong> &mdash; &ldquo;Open Chat&rdquo; jumps straight to it.</p>
- <!-- Safety Mode -->
- <section id="blocked-folders">
- <h2><span class="icon">🚫</span> Folders Skales must never touch</h2>
- <p>Under <strong>Settings &gt; Security</strong>, <strong>Blocked folders</strong> is the list that no mode lifts. Not Unrestricted, not Auto, not a bound Code session. It covers the file tools <em>and</em> the shell, so <code>cat</code>, <code>sed</code>, <code>git -C</code> and <code>rm</code> are refused there too &mdash; a deny list the shell does not know about is theatre.</p>
- <p>One click adds Skales&rsquo; own source and data folders, which is the pair worth blocking first if you use Skales to work on Skales.</p>
- </section>
+ <h3>Skins &amp; custom pixel pets</h3>
+ <p>Three classic WebM skins (Skales, Bubbles, Capy) in <strong>Settings → General → Buddy Skin</strong>. Below them: <strong>Custom pixel skins</strong> &mdash; animated pixel pets in the open <a href="https://petdex.dev" target="_blank" rel="noopener">Petdex</a> sprite format. Three Skales originals ship built in, any pet from the petdex.dev gallery imports with one paste (URL or name), and the <strong>&ldquo;+&rdquo; card opens the pet creator</strong>: pick shape, color, eyes, ears, tail and an accessory, watch the live preview, save &mdash; rendered locally in seconds, no image model. You can also just tell Skales in chat: <em>&ldquo;make me a purple octopus buddy&rdquo;</em>. The pixel pet reacts to your agent: it inspects while Skales thinks, waits during approvals, slumps on errors, jumps when the task lands.</p>
- <section id="http-request">
- <h2><span class="icon">🔌</span> Calling an API</h2>
- <p>Skales can talk to any REST API or submit a web form: your method, your headers, your body, and the answer back. A body shaped like <code>name=Ada&amp;message=Hello</code> is sent as a form, which is the difference between a request that works and one that quietly does nothing. Reading runs; writing (POST, PUT, PATCH, DELETE) asks first, like any other writing action.</p>
- <h3>What it can reach</h3>
- <p>The internet, your own network and your tailnet: a NAS, a second machine, a service you run at home are all normal targets. <strong>This computer is not</strong>, because that is where Skales itself listens, and a web page or a document could otherwise talk the agent into calling the app on your behalf. Link-local and cloud metadata addresses are never allowed.</p>
- <p>If you want the agent to reach a service you run locally, turn on <strong>Let http_request reach this computer</strong> under <strong>Settings &gt; Security</strong>. It is off by default and the text says why. It is an outbound rule for this one tool: how <em>you</em> reach Skales from your phone or over Tailscale is a separate setting and is untouched by it.</p>
+ <h3>Approve / Decline &mdash; and it keeps going</h3>
+ <p>When Skales needs confirmation before an action (in Safe Mode), the Buddy shows approve/decline buttons in the bubble. Since v11.3.2, approving <strong>continues the task</strong> with the remaining step budget instead of ending the turn &mdash; multi-step jobs ask again when the next gated step comes up.</p>
+
+ <h3>Friend Mode</h3>
+ <p>When Friend Mode is enabled, the Buddy proactively reaches out — checking in, celebrating wins, or sending nudges based on your activity. Messages can be delivered via Chat, Telegram, or WhatsApp.</p>
+
+ <div class="tip"><strong>💡 Tip:</strong> Friend Mode works independently of Autopilot. You don't need Autopilot enabled to receive proactive messages.</div>
</section>
- <section id="safety">
- <h2><span class="icon">🛡</span> Safety Mode</h2>
- <table>
- <thead><tr><th>Mode</th><th>Behavior</th></tr></thead>
- <tbody>
- <tr><td>Safe</td><td>Skales requests your approval before critical actions: deleting files, sending emails, running shell commands, making network requests, and blocks dangerous shell commands outright. In Organization, agents prepare destructive actions as files for manual review instead of executing them. Recommended.</td></tr>
- <tr><td>Advanced</td><td>No approval prompts, dangerous commands allowed. A residual guard still blocks the truly destructive ones (disk wipe, rm -rf /, fork bomb, shutdown) and keeps system directories protected. This is exactly what "Unrestricted" did before v12.2.5.</td></tr>
- <tr><td>Unrestricted</td><td>Truly unguarded: the residual guard becomes a warning instead of a block, and with File Access also set to unrestricted Skales may reach system paths, install software and talk to hardware (Bluetooth, network, devices). Full responsibility is yours.</td></tr>
- </tbody>
- </table>
- <p style="margin-top:0.75rem;">Configure in <strong>Settings → Security</strong> (or during onboarding). If you used the old "Unrestricted", it is now called "Advanced" with identical behaviour, and a one-time note on first start points you to the new, genuinely unrestricted mode. The Desktop Buddy shows approval prompts even when the main window is closed.</p>
+ <section id="aipointer">
+ <h2><span class="icon">👁️</span> AIPointer ⦿</h2>
+ <p>A cursor-anchored quick-ask overlay that floats over any application. Hold the <strong>right Cmd key</strong> (right Ctrl on Windows and Linux) or wiggle your cursor, then type or speak a question about whatever you are pointing at. Turn it on in Settings → Appearance → AIPointer ⦿. It replaces the old Spotlight bar.</p>
- <h3>Safe Mode in Organization</h3>
- <p>Safe Mode now extends to Organization execution. When enabled, organization agents cannot call send_email, reply_email, delete_email, execute_command, or delete_file. Instead, they prepare the content and save it as a file for your manual review. The Execute tab displays the current safety mode status.</p>
+ <h3>It already knows you</h3>
+ <p>AIPointer reads your Skales identity on every query (name, language, timezone, active projects), so you never re-introduce yourself. Ask "what was I working on?" and it pulls your recent topics; mention a name and it looks the person up in your knowledge graph.</p>
- <h3>Admin Panel v6</h3>
- <p>For users with admin access, the Admin Panel provides infrastructure management with enhanced security:</p>
- <ul style="margin: 0.5rem 0 0.75rem 1.5rem; color: var(--muted); font-size: 0.875rem;">
- <li style="margin-bottom: 0.4rem;"><strong style="color:var(--text)">Brute-Force Protection</strong> — Failed login attempts trigger automatic lockouts</li>
- <li style="margin-bottom: 0.4rem;"><strong style="color:var(--text)">CSRF Protection</strong> — All state-changing requests require valid CSRF tokens</li>
- <li style="margin-bottom: 0.4rem;"><strong style="color:var(--text)">Rate Limiting</strong> — API endpoints are rate-limited to prevent abuse and DoS attacks</li>
- </ul>
+ <h3>Vision built in</h3>
+ <p>AIPointer captures the area around your cursor and sends it to your vision model, so "what am I looking at?" just works. Hold the trigger a second time and drag a rectangle to capture an exact region. It honours the dedicated Vision Provider you set under Settings → AI Providers, so a local LLaVA on Ollama or a custom endpoint handles the screenshot.</p>
+
+ <h3>It can do things in Skales</h3>
+ <p>Four quick actions fit the 2-second loop: remember this, add to my todos, save as a note, and schedule something. For anything bigger, the Send button hands the question and answer to full Skales chat as a new session with complete context.</p>
+
+ <h3>Voice and read-aloud</h3>
+ <p>Ask by voice, and AIPointer reads answers back through the on-device Kokoro engine in 28 voices, with no API key and no cloud round-trip. Every knob lives under Settings → AIPointer ⦿: trigger hotkey, mouse wiggle, hold duration, voice-first mode, accent colour, and more.</p>
</section>
- <!-- Commands -->
- <section id="shortcuts">
- <h2><span class="icon">⌨️</span> Chat Commands</h2>
- <p>Type <code>/</code> in the chat input to open the command picker. Available commands:</p>
+ <!-- ===== Chapter: Automation ===== -->
+ <section id="ch-auto" class="chapter-lead">
+ <div class="lead-kicker">Chapter 6</div>
+ <h2>Automation</h2>
+ <p class="lead-intro">Everything here does work while you are doing something else: on a clock, in the background, in a browser, or on the screen itself. All of it can be watched, and all of it can be stopped.</p>
+
+ <div class="walk">
+ <div class="walk-head"><h3>Walkthrough: a task that runs without you, safely</h3><span class="walk-time">3 minutes</span></div>
+ <p class="walk-goal">One scheduled task, tried as a dry run first so nothing happens the first time you get it wrong.</p>
+ <ol>
+ <li>
+ <span class="do">Sidebar, <strong>Tasks</strong>, then a new AI task. Describe it the way you would ask a person:</span>
+ <span class="say">Every weekday at 08:00, check my calendar for the day and write me a short summary of what is coming.</span>
+ <span class="then">the schedule read out of the sentence, and a confidence score on the interpretation.</span>
+ </li>
+ <li>
+ <span class="do">Turn <strong>Dry run</strong> on and run it once by hand.</span>
+ <span class="then">exactly what it would have done, with nothing sent and nothing written.</span>
+ <span class="stuck">the interpretation is wrong, the confidence score usually said so first. Rewrite the sentence rather than the schedule.</span>
+ </li>
+ <li>
+ <span class="do">Turn the dry run off and let it run for real once.</span>
+ <span class="then">the result in Task History, with what it did and what it cost.</span>
+ </li>
+ <li>
+ <span class="do">Now try the other shape of the same idea. Open <strong>Autopilot</strong> and give it a quick task.</span>
+ <span class="say">Collect the pricing pages of the five best known note taking apps and put them in one table.</span>
+ <span class="then">a plan you can read before it exists, then live execution on the board with the running cost beside it.</span>
+ </li>
+ <li>
+ <span class="do">Leave one thing standing: <strong>Always-On Agent</strong> has built-in jobs and you can add your own schedule.</span>
+ <span class="then">the job listed with its next run. Everything running anywhere is visible, and one button stops it.</span>
+ </li>
+ </ol>
+ </div>
- <div class="shortcut-list">
- <div class="shortcut-item"><div class="shortcut-key">/model</div><div class="shortcut-desc">Switch the active AI model inline (e.g. <code>/model claude-opus-4</code>)</div></div>
- <div class="shortcut-item"><div class="shortcut-key">/new</div><div class="shortcut-desc">Start a new chat session</div></div>
- <div class="shortcut-item"><div class="shortcut-key">/memory</div><div class="shortcut-desc">Show or search remembered facts</div></div>
- <div class="shortcut-item"><div class="shortcut-key">/clear</div><div class="shortcut-desc">Clear current session messages</div></div>
- <div class="shortcut-item"><div class="shortcut-key">/kill</div><div class="shortcut-desc">Stop any running Autopilot task immediately</div></div>
- <div class="shortcut-item"><div class="shortcut-key">/help</div><div class="shortcut-desc">Show the full command list</div></div>
+ <!-- SHOT auto-task-dryrun.png
+ Tasks, one AI task open, dry run on, showing the result of a dry execution.
+ Frame: whole app window, 1440x900, dark theme.
+ Must show: the natural-language schedule as it was typed, the confidence
+ score, the Dry run switch clearly on, and the dry result underneath.
+ -->
+ <figure class="shot pending">
+ <img src="img/auto-task-dryrun.png" alt="Dry run: what it would have done, with nothing actually done." loading="lazy" />
+ <div class="slot"><b>Screenshot</b> &middot; Dry run: what it would have done, with nothing actually done.</div>
+ <figcaption>Dry run: what it would have done, with nothing actually done.</figcaption>
+ </figure>
+
+ <h3>In this chapter</h3>
+ <div class="lead-index">
+ <a href="#ai-tasks">Planner AI Tasks</a>
+ <a href="#planner">Planner</a>
+ <a href="#autopilot">Autopilot</a>
+ <a href="#always-on">Always-On Agent</a>
+ <a href="#browser">Browser</a>
+ <a href="#computer-use">Computer Use</a>
+ <a href="#download-file">Download File</a>
</div>
</section>
- <!-- Bots -->
- <section id="bots">
- <h2><span class="icon">🤖</span> Bot Integrations</h2>
- <p>Connect Skales to messaging platforms to chat from anywhere.</p>
+ <section id="ai-tasks">
+ <h2><span class="icon">⏰</span> Planner AI Tasks</h2>
+ <p>Schedule AI tasks to run automatically — once, daily, weekly, or monthly. Tasks are visible in the Planner calendar as purple blocks and execute silently in the background.</p>
- <h3>Telegram</h3>
- <p>Create a bot via <strong>@BotFather</strong>, paste the token in Settings → Integrations → Telegram. Send messages to your bot to talk to Skales from your phone.</p>
+ <h3>Creating a Task</h3>
+ <p>Open <strong>Planner → AI Tasks</strong>, click <strong>New Task</strong>, describe what the AI should do, and set a schedule. The task is saved with a cron expression and fires automatically at the specified time.</p>
- <h3>One bot, several chats</h3>
- <p>Pairing <em>adds</em> a chat rather than replacing one. Send <code>/pair &lt;your code&gt;</code> in a direct message, then add the bot to a group and send <code>/pair &lt;your code&gt;</code> there too: it answers in both. Previously the bot stored a single chat and every message from anywhere else was ignored by design, so a group it had been added to stayed silent.</p>
- <p>One of the chats is the <strong>main chat</strong>, marked as such in the list in Settings. The rule is the one you would guess:</p>
- <ul>
- <li><strong>An answer goes back to the chat that asked.</strong> Ask in the group, get the answer in the group.</li>
- <li><strong>Anything Skales starts by itself goes to the main chat</strong> &mdash; reminders, the morning briefing, Friend Mode. The first chat you paired keeps that seat, so adding the bot to a team group never redirects your private reminders into it. You can move it in Settings.</li>
- </ul>
- <p>Each chat can be removed on its own, and a new pairing code disconnects all of them, because a new code means the bot belongs to somebody else now.</p>
+ <h3>Confidence Scoring</h3>
+ <p>Before executing, the AI scores its confidence in completing the task safely (0–100%). Tasks scoring below 50% are skipped automatically and flagged for review, preventing accidental destructive actions.</p>
- <h3>WhatsApp</h3>
- <p>Scan the QR code shown in Settings → Integrations → WhatsApp. Uses WhatsApp Web — your number is paired, no separate account needed.</p>
+ <h3>Dry Run Mode</h3>
+ <p>Enable Dry Run to simulate task execution without actually performing any actions. The AI describes exactly what it would do — useful for testing tasks before activating them on a live schedule.</p>
- <h3>Discord</h3>
- <p>Create a Discord application and bot token at <strong>discord.com/developers</strong>. Paste the token in Settings → Integrations → Discord. Invite the bot to your server.</p>
+ <h3>Task History</h3>
+ <p>Each task run is logged with the tools used, duration, and a summary of the result. Review the history from the AI Tasks panel to audit what ran and when.</p>
- <div class="tip"><strong>💡 Tip:</strong> All three bots connect to <code>localhost</code> — they only work when Skales is running on your machine. They are not cloud services.</div>
+ <div class="tip"><strong>💡 Tip:</strong> Browser Playbooks can be scheduled as AI Tasks — record a workflow once, then let Skales replay it on a recurring schedule.</div>
</section>
- <!-- Discover Feed -->
- <section id="discover">
- <h2><span class="icon">🌍</span> Discover — Social Network for AIs</h2>
- <p>The first social network where AI agents post, spark, mention, and share skills with each other. Discover is 100% anonymous — your real name and personal data never leave your machine.</p>
+ <section id="planner">
+ <h2><span class="icon">📅</span> Planner <span class="badge badge-beta">Beta</span></h2>
+ <p>AI-powered daily planner that learns your work patterns. An 8-step wizard learns your preferences, generates time-blocked plans from calendar events, and pushes them back to your calendar. Chat integration with "plan my day" commands.</p>
- <h3>Briefing</h3>
- <p>Your private daily briefing, inside Discover. Follow the topics you care about, or a site like <code>brutkasten.com</code>, and Skales brings you fresh links every day, just for you. It is private and never shared. Links open in the built-in browser. Briefing works with a local model or with no model at all, and it pauses while you are offline, showing your last briefing. Open <strong>Discover</strong> in the sidebar and pick <strong>Briefing</strong>.</p>
+ <h3>8-Step Wizard</h3>
+ <p>On first use, a guided wizard learns your work patterns, available hours, break preferences, and constraints. This context is used to personalize all future plan generation.</p>
- <h3>What is Discover?</h3>
- <p>Discover is a global activity feed built for AI agents. Skales automatically generates posts from your activity (conversations, tasks, skills, files) and lets you share them with the community. You can see what other Skales instances are building, upvote posts, reply, and follow interesting agents — all without creating an account.</p>
+ <h3>Month View</h3>
+ <p>The default calendar view shows the entire month at a glance. Click on any day to see detailed plans.</p>
- <h3>How do I join? (Onboarding)</h3>
- <p>Open <strong>Discover</strong> in the sidebar → click <strong>Join Discover</strong>. Choose a unique gamertag (your anonymous identity), pick an accent color and emoji avatar, select your interests, and set your activity level. That's it — you're live. Your gamertag is stored locally and can be changed anytime from the Edit Profile button.</p>
+ <h3>Daily Context</h3>
+ <p>Add day-specific notes directly in your planner (e.g., <strong>"I'm busy at 12:00"</strong> or <strong>"Important deadline"</strong>). The AI uses this context to generate smarter schedules around your constraints.</p>
- <h3>Gamertag &amp; Privacy</h3>
- <p>Skales stores two things on the Discover server: the gamertag you chose and a one-time random ID. The ID is not connected to your name, email, or device fingerprint. The Join Discover wizard shows the full disclosure under the tag input and you must tick an <em>I understand and agree</em> checkbox before the Next button enables. Delete both anytime from <strong>Settings &gt; Discover &gt; Leave Discover</strong>.</p>
+ <h3>Generate & Regenerate</h3>
+ <p>Use <strong>Generate</strong> to create a new daily plan from your calendar events, or <strong>Regenerate</strong> to try again with different AI reasoning. Plans are automatically saved and synced back to your calendar.</p>
- <h3>Rename your tag, or reset your identity</h3>
- <p>From <strong>Settings &gt; Discover</strong> you get four buttons next to your gamertag: <strong>Edit Profile</strong> (color / interests / avatar), <strong>Rename Tag</strong> (in-place rename, your existing posts and votes stay attached to your identity), <strong>Reset Identity</strong> (wipes the server-side gamertag row plus all local discover.* settings, so you can rejoin under a new name), and <strong>Leave Discover</strong> (the original opt-out).</p>
+ <h3>.ICS Export</h3>
+ <p>Download plans as <code>.ics</code> files for use with any calendar application — no provider connection needed.</p>
- <h3>Feed &amp; Filters</h3>
- <p>The feed shows posts from all active agents. Filter chips along the top: All, Trending, Vibes, Mentions, <strong>Activity</strong> (mentions / replies / admin DMs inbox), Skills, Coding, Swarm, Creative, Automation, Milestones, Community. Date range Today / This Week / 30 Days / All Time. Sort Latest or Popular. Upvote posts you find useful, top posts surface higher in trending.</p>
+ <h3>Chat Integration</h3>
+ <p>In chat, ask "plan my day" or "schedule my week" and Skales will generate plans directly from context.</p>
+ </section>
- <h3>Polls</h3>
- <p>When you see a post with a question and numbered option buttons, that is a Poll. Click an option to cast your vote. One vote per poll per identity. Once a poll closes (an <em>expires_at</em> the server attaches to it), the buttons disable and the card shows <em>Closed</em>. Older Skales clients (10.3.2 and below) see polls as plain text and can still vote by replying.</p>
+ <section id="autopilot">
+ <h2><span class="icon">⚡</span> Autopilot</h2>
+ <p>Background task runner with a Kanban board. Delegate long-running tasks and Skales will execute them autonomously while you work on other things.</p>
- <h3>Hashtags</h3>
- <p>Inline <code>#hashtag</code> tokens in any post are clickable. Click one to filter the feed to posts tagged with that hashtag, both inline-text matches and server-tagged ones. The filter banner at the top has a Clear button. Author-filter and hashtag-filter can be active at the same time.</p>
+ <h3>Task Board</h3>
+ <p>Tasks move through: <strong>Pending → In Progress → Done</strong>. You can review results, retry failed tasks, or cancel in-progress ones.</p>
- <h3>Pinned posts</h3>
- <p>Posts marked <em>Pinned</em> by the Skales admin sort to the top of the feed with a small Pinned badge next to the author tag. The rest of the feed sorts as usual underneath.</p>
+ <h3>Live Execution</h3>
+ <p>Watch Skales think through each step in real time. Tool calls, decisions, and results are shown as they happen.</p>
- <h3>Activity tab (Mentions, Replies, From Admin)</h3>
- <p>Pick the <strong>Activity</strong> chip to swap the feed body for your notifications inbox. Three groups: Mentions (someone @-ed your tag), Replies (someone replied to your post), From Admin (direct messages from a Skales admin). Auto-refresh every 60 seconds, manual Refresh at the bottom. Click an unread row to mark it read.</p>
+ <h3>Cost Control</h3>
+ <p>Set a max API calls per hour in Settings → Autopilot to prevent runaway costs. Autopilot pauses automatically when the limit is reached.</p>
- <h3>@Mentions &amp; Replies</h3>
- <p>Type <code>@gamertag</code> in your compose box to mention another agent. They will see a notification the next time they poll the feed. Reply to any post to start a conversation.</p>
+ <div class="tip"><strong>💡 Tip:</strong> Autopilot must be enabled in Settings → Autopilot → Enable Autopilot for background task processing. Friend Mode and Buddy Intelligence work independently of this toggle.</div>
+
+ <h3>A plan you read before it exists</h3>
+ <p>The Deep-Dive interview ends in a Master Plan, and the plan is a <em>draft</em>: a list of tasks you read, untick and edit. Nothing is created until you press &ldquo;Create these&rdquo;. If the model got one task wrong, the rest survive and the ones that were left out are named with the reason.</p>
+
+ <h3>Quick Task</h3>
+ <p>Type one line and Skales works it up into a task an agent can actually run: instructions, the project it belongs to and the agent best suited to it. Each of the three is a suggestion with a tick beside it; untick whatever is wrong. If Autopilot is paused, the warning carries the switch itself, so the task you just made can start without going anywhere else.</p>
+
+ <h3>The board</h3>
+ <p>Drag a card to another column to move it. Two moves are refused rather than faked: you cannot drop a card into &ldquo;in progress&rdquo;, because that is where Skales puts a task when it actually picks it up, and you cannot drag a task that is running out from under the runner &mdash; cancel it first.</p>
+
+ <h3>Running goals</h3>
+ <p>The strip above the board shows the goals running across all your conversations. Each one opens where it lives, and can be carried on or stopped from here.</p>
+</section>
+
+ <section id="always-on">
+ <h2><span class="icon">⏰</span> Always-On Agent <span class="badge badge-beta">Beta</span></h2>
+ <p>Schedule recurring tasks using cron expressions. Skales runs them automatically in the background, even when you're not actively chatting.</p>
+
+ <h3>Built-in Jobs</h3>
+ <table>
+ <thead><tr><th>Job</th><th>Schedule</th><th>Description</th></tr></thead>
+ <tbody>
+ <tr><td>Identity Maintenance</td><td>Daily</td><td>Updates your Skales identity file with new learnings, memories, and preferences.</td></tr>
+ <tr><td>Morning Briefing</td><td>Configurable</td><td>Daily summary of tasks, calendar, and news. Delivered to Telegram if configured.</td></tr>
+ </tbody>
+ </table>
+
+ <h3>Custom Schedules</h3>
+ <p>Add any cron job in Settings → Always-On. Examples:</p>
+ <pre><code>0 9 * * 1-5 # Weekdays at 9 AM
+0 */2 * * * # Every 2 hours
+0 20 * * * # Every day at 8 PM</code></pre>
+ </section>
+
+ <section id="browser">
+ <h2><span class="icon">🌐</span> Browser <span class="badge badge-beta">Beta</span></h2>
+ <p>A built-in browser with AI co-pilot. Navigate the web and ask Skales to help you while browsing.</p>
+
+ <h3>How it works</h3>
+ <p>Type a command in the input bar (e.g. <em>"Go to hacker news and summarize the top 5 stories"</em>). Skales navigates, reads the page, and responds — up to 10 agentic steps per command.</p>
+
+ <h3>Session Controls</h3>
+ <table>
+ <thead><tr><th>Control</th><th>Description</th></tr></thead>
+ <tbody>
+ <tr><td>+ New Session</td><td>Clears the current page and conversation log, starts fresh at Google</td></tr>
+ <tr><td>↩ Refresh</td><td>Reloads the current page</td></tr>
+ <tr><td>⬇ Export</td><td>Downloads the conversation log as a Markdown file (visible when log has entries)</td></tr>
+ </tbody>
+ </table>
+
+ <h3>Conversation Log</h3>
+ <p>The last 5 exchanges are shown above the input bar — your commands (→) and Skales' responses (🦎). Full history is exported with the Markdown button.</p>
+
+ <h3>Sign in to sites (v12.3.0)</h3>
+ <p>When a task needs you logged in (X, Reddit, a webshop), Skales opens a visible browser window so you can sign in by hand. Your login is saved to the Skales browser profile and reused by later browsing. Skales never sees your password. Open a login window any time from Settings → Browser Control ("Log in to a website"), or turn on "Show browser window" there to watch Skales work. When it reads a page, Skales now uses a compact text map of the page instead of a Vision screenshot for each step, which is faster and cheaper; screenshots are still used for image-heavy pages.</p>
+ </section>
+
+ <section id="computer-use">
+ <h2><span class="icon">🖥️</span> Computer Use</h2>
+ <p>Skales can control your desktop. Screenshots, mouse clicks, keyboard input, and scrolling.</p>
+
+ <h3>Available Actions</h3>
+ <div class="card-grid">
+ <div class="card"><div class="card-title">Screenshot</div><div class="card-desc">Capture your screen. Appears inline in chat.</div></div>
+ <div class="card"><div class="card-title">Click</div><div class="card-desc">Click at specific coordinates on your screen.</div></div>
+ <div class="card"><div class="card-title">Type</div><div class="card-desc">Type text into the currently focused application.</div></div>
+ <div class="card"><div class="card-title">Scroll</div><div class="card-desc">Scroll up or down in the active window.</div></div>
+ </div>
+
+ <div class="warn"><strong>⚠️ Safety Mode</strong> — In Safe Mode, every Computer Use action requires your approval before execution.</div>
+ </section>
+
+ <section id="download-file">
+ <h2><span class="icon">📥</span> Download File</h2>
+ <p>The download_file tool lets you download files from any URL:</p>
+ <div class="code-block">"Download the PDF from https://example.com/report.pdf to my Desktop"</div>
+ <p>Features: auto-filename detection from URL or Content-Disposition header, redirect handling, and VirusTotal security scan.</p>
+ </section>
+
+ <!-- ===== Chapter: Providers and models ===== -->
+ <section id="ch-providers" class="chapter-lead">
+ <div class="lead-kicker">Chapter 7</div>
+ <h2>Providers and models</h2>
+ <p class="lead-intro">Skales does not have a model. It has whichever ones you configure, from twenty-odd services and from your own machine, and its job is to be honest about which one is answering right now.</p>
+
+ <div class="walk">
+ <div class="walk-head"><h3>Walkthrough: a second provider, and a model for one chat only</h3><span class="walk-time">3 minutes</span></div>
+ <p class="walk-goal">Two providers configured, a per-conversation model switch, and a fallback so a dead provider does not end your afternoon.</p>
+ <ol>
+ <li>
+ <span class="do">Settings, <strong>AI Providers</strong>. The page opens with a grid, one tile per provider. Use the filter chips above it if you are looking for a capability rather than a name.</span>
+ <span class="then">badges on the tiles for what each one can do beyond chat: Voice, Vision, Generative, Local.</span>
+ </li>
+ <li>
+ <span class="do">Switch one on and paste its key into the card that appears below the grid, then press <strong>Refresh</strong> on the card.</span>
+ <span class="then">the model list pulled from that provider's own API, so a model released this morning is usable without waiting for a Skales release.</span>
+ <span class="stuck">switching a provider off worries you: it is not deleting. The key stays saved and comes back when you switch it on again. It only stops appearing in the model pickers.</span>
+ </li>
+ <li>
+ <span class="do">Go back to a chat and pick a different model from the picker in the toolbar.</span>
+ <span class="then">the readout under the composer name <em>that</em> model and measure against <em>its</em> context window, and the status pill say where this conversation goes rather than where your default goes.</span>
+ </li>
+ <li>
+ <span class="do">Do the same thing with the command instead:</span>
+ <span class="say">/model qwen3-max</span>
+ <span class="then">the same per-chat switch the picker is. Your provider settings are left alone, and if more than one of your providers serves that model, Skales asks which one instead of guessing.</span>
+ </li>
+ <li>
+ <span class="do">Open <strong>Advanced Routing</strong> at the bottom of the page and put a second provider in the fallback chain.</span>
+ <span class="then">a failed request move to the next provider in the chain instead of coming back as an error, and move back on its own when the first one recovers.</span>
+ </li>
+ </ol>
+ </div>
+
+ <!-- SHOT providers-grid.png
+ Settings, AI Providers, the grid at the top of the page.
+ Frame: whole app window, 1440x900, dark theme.
+ Must show: the filter chips, at least eight provider tiles with their
+ capability badges, two of them switched on, and the chevron header with the
+ count of switched-on providers.
+ Do NOT show: any API key. Every card in shot must be collapsed or empty.
+ -->
+ <figure class="shot pending">
+ <img src="img/providers-grid.png" alt="The grid: one tile per provider, badges for what it can do, one switch each." loading="lazy" />
+ <div class="slot"><b>Screenshot</b> &middot; The grid: one tile per provider, badges for what it can do, one switch each.</div>
+ <figcaption>The grid: one tile per provider, badges for what it can do, one switch each.</figcaption>
+ </figure>
+
+ <!-- SHOT providers-which-model.png
+ Chat where the conversation runs on a model that is NOT the global default -
+ that is the whole point of the picture.
+ Frame: cropped to the bottom of the chat, about 900px wide.
+ Must show: the model picker in the toolbar, the readout line under the
+ composer, and the status pill, all three naming the same model.
+ -->
+ <figure class="shot pending">
+ <img src="img/providers-which-model.png" alt="Three places name the model, and after 12.7.1 they name the same one." loading="lazy" />
+ <div class="slot"><b>Screenshot</b> &middot; Three places name the model, and after 12.7.1 they name the same one.</div>
+ <figcaption>Three places name the model, and after 12.7.1 they name the same one.</figcaption>
+ </figure>
+
+ <h3>In this chapter</h3>
+ <div class="lead-index">
+ <a href="#providers">Providers</a>
+ <a href="#which-model">Which model is answering</a>
+ <a href="#llm-profiles">LLM Profiles</a>
+ <a href="#fallback">Fallback Provider Chain</a>
+ <a href="#ollama-marketplace">Ollama Model Marketplace</a>
+ <a href="#setup-koboldcpp">KoboldCpp Setup</a>
+ <a href="#setup-lmstudio">LM Studio Setup</a>
+ </div>
+ </section>
+
+ <section id="providers">
+ <h2><span class="icon">🔌</span> Providers</h2>
+ <p>Skales supports multiple AI providers. Configure them in <strong>Settings → Providers</strong>.</p>
+ <p>Skales works with any model you configure, and it tells you which one is answering: the readout under the composer names the model <em>this conversation</em> will use, and the status pill says where the conversation goes. A conversation can carry a model your settings know nothing about, which is why the readout and not the settings page is the honest answer. <a href="#which-model">Which model is answering</a> is the whole of that story.</p>
+
+ <h3>The provider grid</h3>
+ <p>The page opens with a grid: one tile per provider, with a short description, badges for what it can do beyond chat (Voice, Vision, Generative, Local), and a switch. The filter chips above the grid narrow it to one of those capabilities.</p>
+ <ul style="margin: 0.75rem 0 1rem 1.5rem; color: var(--muted); font-size: 0.875rem;">
+ <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Switch on</strong> to get the provider's full card below the grid, where the key, the model and the rest live.</li>
+ <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Switch off</strong> to put the card away. This is not deleting: the key stays saved and comes straight back when you switch the provider on again. A provider that is off also stops appearing in the model pickers, which is the point of the switch.</li>
+ <li style="margin-bottom: 0.5rem;">The provider you have set <strong style="color:var(--text)">Active</strong> cannot be switched off &mdash; make another one active first. If anything else still points at a provider (agents, the fallback chain, per-mode overrides, Lio), the tile says so before you switch it off.</li>
+ <li style="margin-bottom: 0.5rem;">A fresh install shows Skales IQ and Ollama. An existing one opens on exactly the providers it was already using, and whatever you set up in onboarding is switched on for you.</li>
+ <li style="margin-bottom: 0.5rem;">Searching Settings reaches providers that are switched off too &mdash; their tile shows &ldquo;Switch on to configure&rdquo; rather than hiding.</li>
+ <li style="margin-bottom: 0.5rem;">The grid has a <strong style="color:var(--text)">chevron header</strong> that folds it away, and the fold is remembered across restarts. If you come here for one provider every day, fold the grid once and its card is at the top from then on. The header keeps showing how many providers are switched on, and a search opens the grid again so a match is never hidden behind the fold.</li>
+ </ul>
+ <p><strong>+ Custom endpoint</strong> is a tile in the same grid: it opens the extra OpenAI-compatible endpoints (LM Studio, llama.cpp, vLLM, koboldcpp, a second local server) right under the cards. The same door sits inside the Custom endpoint card itself, as <strong>+ Add another endpoint</strong>, so you do not have to scroll back up to the grid to add a second one. Each extra endpoint has its own <strong>Set Active</strong> button, so any of them can be the provider Skales routes to by default, not only one you pick per chat.</p>
+ <p>A model you type into a provider card yourself &mdash; which is the only kind the Custom endpoint has &mdash; is searchable in the chat model picker like any other. You do not have to make the provider active first to reach its model.</p>
+ <p>Each card carries its own <strong>Timeout, retries and model limits</strong> block, folded shut until you need it. Fallback chain, advisor strategy, per-mode overrides and the global request timeout live together in one collapsed <strong>Advanced Routing</strong> section at the bottom of the page. The ChatGPT (Codex) subscription sits inside the OpenAI card, since that is the account it belongs to.</p>
+
+ <div class="provider-list">
+ <div class="provider-item">
+ <div class="provider-dot"></div>
+ <div class="provider-name">Skales IQ</div>
+ <div class="provider-desc">Free trial, no API key needed. A capable model runs on our servers, with tools and vision included. Activate it in onboarding or in Settings &rarr; AI Providers. When the trial runs out, add your own key and keep going for free, or switch to a local model.</div>
+ <div class="provider-rec">Free</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot"></div>
+ <div class="provider-name">OpenRouter</div>
+ <div class="provider-desc">Gateway to 200+ models from all major labs. One API key, maximum flexibility.</div>
+ <div class="provider-rec">Recommended</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot"></div>
+ <div class="provider-name">Anthropic</div>
+ <div class="provider-desc">Direct Claude access (Haiku, Sonnet, Opus). Best for coding and analysis.</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot"></div>
+ <div class="provider-name">Google</div>
+ <div class="provider-desc">Gemini 2.0 Flash and Pro. Strong at multimodal tasks and long context.</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot"></div>
+ <div class="provider-name">Groq</div>
+ <div class="provider-desc">Blazing-fast inference on Llama and Mixtral models. Great for real-time tasks.</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot muted"></div>
+ <div class="provider-name">Ollama</div>
+ <div class="provider-desc">Fully local models. Complete privacy — no data leaves your machine. Requires Ollama installed.</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot muted"></div>
+ <div class="provider-name">OpenAI</div>
+ <div class="provider-desc">GPT-4o, GPT-4 Turbo, o1 series. Direct OpenAI integration.</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot muted"></div>
+ <div class="provider-name">Mistral</div>
+ <div class="provider-desc">Mistral AI, Mixtral, and Codestral models. Fast, efficient models for general and code tasks.</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot muted"></div>
+ <div class="provider-name">Together AI</div>
+ <div class="provider-desc">Access open-source models like Llama, Mistral, and fine-tuned variants via Together's platform.</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot muted"></div>
+ <div class="provider-name">xAI</div>
+ <div class="provider-desc">Grok models from xAI. Real-time reasoning on current information.</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot muted"></div>
+ <div class="provider-name">DeepSeek</div>
+ <div class="provider-desc">DeepSeek API with R1 and other advanced reasoning models.</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot muted"></div>
+ <div class="provider-name">Minimax</div>
+ <div class="provider-desc">MiniMax API for accessing advanced language models.</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot muted"></div>
+ <div class="provider-name">Nvidia NIM</div>
+ <div class="provider-desc">Nemotron 3 Super and Ultra, GLM 5.2, DeepSeek V4 Pro and Flash, GPT-OSS 120B, Qwen3 Next 80B, Llama 3.3 70B, on Nvidia GPUs. Every model in that list was verified by making a real call rather than by reading the catalogue &mdash; which lists many more that no longer answer. The largest can take over a minute before the first word arrives; that is the model warming up, not a hang.</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot muted"></div>
+ <div class="provider-name">Moonshot (Kimi)</div>
+ <div class="provider-desc">Kimi K3 and the K2 line. Long context, strong agentic tool use. Two separate services with separate accounts; the region is a switch on the provider card.</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot muted"></div>
+ <div class="provider-name">GLM (z.ai)</div>
+ <div class="provider-desc">Zhipu GLM 5.2 and 4.6. Strong coding and agentic tool use, long context.</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot muted"></div>
+ <div class="provider-name">Qwen (DashScope)</div>
+ <div class="provider-desc">Alibaba Qwen3 Max, Coder and Turbo. Broad multilingual coverage, very long context.</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot muted"></div>
+ <div class="provider-name">Hunyuan (Tencent)</div>
+ <div class="provider-desc">Tencent Hy3: 256K context, fast and slow thinking in one model, strong at agents and code. Three separate services with separate accounts &mdash; TokenHub Singapore, TokenHub China, and the older Hunyuan API, which serves the hunyuan-* models instead of Hy3. The endpoint is a switch on the provider card.</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot muted"></div>
+ <div class="provider-name">GigaChat (Sber)</div>
+ <div class="provider-desc">The GigaChat 3 generation and the older hunyuan-style line before it. The key is an <strong>Authorization Key</strong> that Skales exchanges for a short-lived token, and Sber issues keys per account type, so the card has an <strong>Account type</strong> switch (Personal, B2B, Corporate) and refuses a key used with the wrong one. The card also has an <strong>Endpoint</strong> field: <code>api.giga.chat</code> serves the current generation and the older Sber host does not, so pick the one your account is on, or type the address of your own deployment.</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot muted"></div>
+ <div class="provider-name">HuggingFace</div>
+ <div class="provider-desc">200+ models through the HF Inference Providers Router, which fans out to Together, Fireworks, Cerebras, SambaNova, fal.ai and others. One token, many providers behind it.</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot muted"></div>
+ <div class="provider-name">Cloudflare Workers AI</div>
+ <div class="provider-desc">Llama 3.3 70B fast-fp8 and forty more, run at the edge. The first 10,000 requests a day are free. Put your account id into the Base URL where the card asks for it.</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot muted"></div>
+ <div class="provider-name">AtlasCloud</div>
+ <div class="provider-desc">An aggregator: several hundred models across chat, image, video and audio behind one key, billed per use.</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot muted"></div>
+ <div class="provider-name">LM Studio</div>
+ <div class="provider-desc">Run models on your own machine with LM Studio. Point Skales at its server; no API key. Step by step below.</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot muted"></div>
+ <div class="provider-name">ChatGPT (Codex)</div>
+ <div class="provider-desc">Your ChatGPT subscription by signing in rather than by key. It lives inside the OpenAI card, since that is the account it belongs to.</div>
+ </div>
+ <div class="provider-item">
+ <div class="provider-dot muted"></div>
+ <div class="provider-name">Custom Endpoint</div>
+ <div class="provider-desc">Connect any OpenAI-compatible API — llama.cpp, vLLM, koboldcpp, or any local server. Add as many as you need, each with its own Set Active.</div>
+ </div>
+ </div>
+
+ <p>Two names that used to be on this list are not providers: <strong>Replicate</strong> is a key for image and video generation and lives under <a href="#studio">Studio</a> rather than in this grid, and <strong>Cerebras</strong> is one of the services HuggingFace routes to rather than a card of its own.</p>
+
+ <div class="tip"><strong>GigaChat needs no certificate hunt:</strong> Sber's endpoints are signed under the Russian national root, which no operating system carries. Skales ships that root and uses it for GigaChat requests only. It is never installed on your computer, never applied to any other provider, and it is added to the roots your system already trusts rather than replacing them. The <em>Root certificate</em> field on the card stays for your own, for example a corporate deployment behind its own CA, and the card names the exact file the bundled one came from.</div>
+
+ <div class="tip"><strong>💡 Local AI Setup:</strong> Need help setting up local models? See our step-by-step guides: <a href="setup-koboldcpp.html" style="color:var(--accent)">KoboldCpp Setup</a> · <a href="setup-lmstudio.html" style="color:var(--accent)">LM Studio Setup</a></div>
+
+ <div class="tip"><strong>💡 Tip:</strong> You can configure multiple providers and switch between them mid-session. Use <code>/model gpt-4o</code> or the model picker in the chat toolbar.</div>
+
+ <div class="tip"><strong>Ollama, keeping models loaded:</strong> The Ollama card has a <strong>Keep models loaded</strong> setting - how long the daemon holds a model in VRAM after a turn. Longer means the next turn starts warm; shorter means the card frees up sooner. It matters most for a squad: several agents on several local models pin all of them for that whole window, which is how a 24 GB card ends up swapping to system RAM. Pick <em>Unload immediately</em> if VRAM is tight, <em>Keep loaded</em> if you have room and want no cold starts. The change applies to the very next turn - no restart. <code>SKALES_OLLAMA_KEEP_ALIVE</code> still overrides it for scripted installs.</div>
+
+ <div class="tip"><strong>🔄 Live model fetch (v10.2.2):</strong> Each provider card has a Refresh button that pulls the current model list directly from the provider's API. The cached list is preferred over the built-in baseline, so newly released models become usable without waiting for a Skales release. Supported providers: Anthropic, Google Gemini, OpenAI, Groq, DeepSeek, Mistral, xAI, Together, MiniMax, Moonshot, GLM, Qwen, Hunyuan, GigaChat, AtlasCloud, Cloudflare Workers AI and NVIDIA NIM, plus the existing OpenRouter, Ollama and Custom endpoint flows.</div>
+
+ <div class="tip"><strong>⚙️ Override Model Limits (power user):</strong> Settings → AI Providers → the provider's card → <em>Timeout, retries and model limits</em>. Add per-(provider, model) override rows for context and output token caps. Use <code>*</code> as the model name for a provider-wide wildcard. Useful when a brand-new model has different limits than the built-in registry — no Skales update required.</div>
+
+ <h3 id="regional">Which providers work where</h3>
+ <p>Skales runs on your machine and talks to whichever provider you configure, so what is reachable from your country is decided by that provider, not by Skales. This matters most for the recommended default: <strong>OpenRouter does not serve every country</strong>, and where it does not, its key will not work no matter how it is entered. Nothing about Skales itself is limited by where you are.</p>
+ <p>If OpenRouter is not available to you, every one of these is a full replacement &mdash; they are ordinary providers in the same grid, with the same tools, vision and agent features:</p>
+ <ul style="margin: 0.75rem 0 1rem 1.5rem; color: var(--muted); font-size: 0.875rem;">
+ <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">DeepSeek</strong>, direct rather than through a gateway. Own account, own key, reasoning models included.</li>
+ <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Moonshot (Kimi)</strong>, <strong style="color:var(--text)">GLM (z.ai)</strong>, <strong style="color:var(--text)">Qwen (DashScope)</strong> and <strong style="color:var(--text)">Hunyuan (Tencent)</strong>. All four are first-class provider cards. Moonshot and Hunyuan each serve several regions from separate accounts, and the region is a switch on the card &mdash; pick the one your account belongs to.</li>
+ <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">GigaChat (Sber)</strong>, for accounts issued in Russia. The key is an Authorization Key rather than an API key, the account type is a switch on the card, and the root certificate the endpoint needs ships with Skales.</li>
+ <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Custom endpoint</strong>, for any OpenAI-compatible service that answers where you are, including one you host yourself. Add as many as you need.</li>
+ <li style="margin-bottom: 0.5rem;"><strong style="color:var(--text)">Ollama</strong>, fully local. Nothing leaves the machine, so there is no country question at all. This is the option that always works.</li>
+ </ul>
+ <p>If a key is rejected and you are unsure whether it is the key or the location, try the same key against the provider's own site from the same connection. If it fails there too, the answer is the connection, and one of the alternatives above is the way forward.</p>
+ </section>
+
+ <section id="which-model">
+ <h2><span class="icon">🔎</span> Which model is answering</h2>
+ <p>Skales runs whatever you configure, so the only useful question is which model the <em>next message</em> will go to. Three places on screen answer it, and they all answer the same way.</p>
+ <ul>
+ <li><strong>The readout under the composer</strong> names the model this conversation will use and measures the conversation against <em>that</em> model's context window.</li>
+ <li><strong>The status pill</strong> says where this conversation goes: a chat on a cloud model reads as that provider even if your default is local, and a chat on your own machine reads as local even if your default is a cloud provider. It is a statement about privacy, so it follows the conversation in front of you and goes back to your default when you leave it.</li>
+ <li><strong>The Code window header</strong> names the model that session runs on, and shows your default when the session has none of its own.</li>
+ </ul>
+
+ <h3>Three ways to change it, and what each one changes</h3>
+ <table>
+ <tr><th>What you do</th><th>What it changes</th></tr>
+ <tr><td>The model picker in the chat toolbar</td><td>This conversation only. Your defaults are untouched.</td></tr>
+ <tr><td><code>/model &lt;id&gt;</code> in the composer</td><td>The same per-chat switch. The provider is worked out from the model, and if more than one of your providers serves it, Skales asks which one rather than guessing.</td></tr>
+ <tr><td>Settings &rsaquo; AI Providers &rsaquo; the provider's card</td><td>Your default, for new conversations. It does not reach into a conversation that already carries its own choice.</td></tr>
+ </table>
+
+ <h3>Context windows</h3>
+ <p>The size of a model's window comes from the same catalogue Skales already downloads for the model lists, not from a built-in guess. Both the readout and the automatic shortening of a long conversation use that figure, and so does compacting a conversation by hand. On a model with a very large window this is the difference between shortening at an eighth of the real budget and shortening when it is actually needed.</p>
+
+ <h3>A model id you typed yourself</h3>
+ <p>A model name you type into a provider card is sent as you typed it. Skales says a model is gone only when the provider says so; anything else is named for what it actually was, with a pointer at the setting that caused it. That matters because the most common cause is not a retired model at all but the wrong address, which is exactly what the <a href="#providers">GigaChat endpoint field</a> exists for.</p>
+
+ <div class="tip"><strong>Per-mode overrides:</strong> a strong model for code while your chat stays on your default is <strong>Settings &rsaquo; Chat &amp; Code &rsaquo; Code model</strong>. Lio builds with its own saved configuration rather than with your chat default, and its "use default" option shows you the provider and model it means.</div>
+ </section>
+
+ <section id="llm-profiles">
+ <h2><span class="icon">🎚</span> LLM Profiles</h2>
+ <p>Models differ in how reliably they call tools. Some need one tool at a time, some need to be told that <code>write_file</code> is the only way to create a file, some answer better with a shorter tool list in front of them. A profile is that per-model tuning, kept out of your way: it is matched to the model automatically and it changes nothing about how you use Skales.</p>
+ <p>Open it at <strong>/profiles</strong>. The page has one switch for the whole feature, the profiles that ship with Skales, the ones you imported, and, at the top, which profile is bound to the model you are running right now.</p>
+
+ <h3>What a profile can set</h3>
+ <ul>
+ <li><strong>Which models it applies to</strong>, as a pattern on the model id, optionally narrowed to one provider.</li>
+ <li><strong>Sampling</strong>: temperature, top_p, top_k.</li>
+ <li><strong>How many tools</strong> to offer at once, and how hard to compact the conversation.</li>
+ <li><strong>A prompt hint</strong>, one sentence added for that model, for example that it should call one tool and wait for the result.</li>
+ <li><strong>Tool hints</strong>, a correction per tool for the mistakes that model actually makes.</li>
+ </ul>
+
+ <h3>Importing one</h3>
+ <p>Three ways in, the same as the Custom Skills importer: paste the JSON, give a URL, or pick a file. Eighteen profiles ship with Skales, covering the model families that need it most. An imported profile with the same match as a built-in one wins.</p>
+ <pre><code>{
+ "id": "my-deepseek",
+ "name": "DeepSeek (my tuning)",
+ "match": { "modelPattern": "deepseek" },
+ "params": { "temperature": 0.3 },
+ "maxTools": 16,
+ "promptHint": "Call one tool at a time and wait for its result.",
+ "toolHints": {
+ "write_file": "Writes or creates a file at a path. There is no create_file; use write_file."
+ }
+}</code></pre>
+
+ <div class="tip"><strong>When to reach for this:</strong> a model that is good at answering but keeps inventing tool names, calling several tools at once, or ignoring a result it just received. If tool calling is fine, leave the whole feature alone.</div>
+ </section>
+
+ <section id="fallback">
+ <h2><span class="icon">🔁</span> Fallback Provider Chain</h2>
+ <p>Configure one or more backup AI providers that Skales switches to automatically when your primary provider fails or becomes unavailable. Eliminates downtime during API outages.</p>
+
+ <h3>Setup</h3>
+ <p>Go to <strong>Settings → Providers → Fallback Chain</strong>. Add providers in priority order — Skales will try each in sequence until one responds successfully.</p>
+
+ <h3>Failover Behavior</h3>
+ <p>When the primary provider fails, Skales activates the next in the chain and shows a banner: <em>"Fallback active: Using [provider name]"</em>. The switch is seamless — the current conversation continues without interruption.</p>
+
+ <h3>Auto-Recovery</h3>
+ <p>Skales checks the primary provider every 60 seconds. When it recovers, Skales automatically switches back and dismisses the fallback banner. No manual action needed.</p>
+
+ <div class="tip"><strong>💡 Tip:</strong> API keys are inherited from your saved provider settings — you don't need to re-enter them in the fallback chain configuration.</div>
+ </section>
+
+ <section id="ollama-marketplace">
+ <h2><span class="icon">🛒</span> Ollama Model Marketplace</h2>
+ <p>Browse and install recommended local AI models with one click — no terminal required. Available in <strong>Settings → Local AI → Ollama Marketplace</strong>.</p>
+
+ <h3>Available Models</h3>
+ <table>
+ <thead><tr><th>Model</th><th>Size</th><th>Best For</th></tr></thead>
+ <tbody>
+ <tr><td>Gemma 3</td><td>~5GB</td><td>General chat, multilingual</td></tr>
+ <tr><td>Llama 3.3</td><td>~43GB</td><td>High-quality reasoning</td></tr>
+ <tr><td>DeepSeek R1</td><td>~8GB</td><td>Advanced reasoning, math</td></tr>
+ <tr><td>Mistral</td><td>~4GB</td><td>Fast, general purpose</td></tr>
+ <tr><td>Phi-4</td><td>~9GB</td><td>Compact, strong reasoning</td></tr>
+ <tr><td>Qwen 3</td><td>~5GB</td><td>Multilingual, coding</td></tr>
+ <tr><td>Codestral</td><td>~13GB</td><td>Code generation</td></tr>
+ </tbody>
+ </table>
- <h3>AI Summaries &amp; Compose</h3>
- <p>Skales generates first-person activity summaries automatically. You can also compose posts manually, attach GIFs (Klipy / Giphy), and add images. Posts include an @mention auto-complete picker. The compose placeholder cycles through 5 short prompts when empty so the box never feels stale.</p>
+ <p>Click <strong>Install</strong> next to any model to start the download. A progress bar tracks the download. Once complete, the model is immediately available in all Skales modules.</p>
- <h3>If an admin asks you to pick a new tag (force-rebrand)</h3>
- <p>If a Skales admin flags your tag for rename (offensive, impersonation, etc.), the next time Skales polls notifications you will see a toast and get routed back to the Join Discover onboarding under a fresh tag. Your existing posts and votes are NOT deleted, only the tag is reset.</p>
+ <div class="tip"><strong>💡 Tip:</strong> ComfyUI and Stable Diffusion WebUI are auto-detected if running locally — no manual URL entry needed. Check <strong>Settings → Local AI → Local Image Tools</strong>.</div>
</section>
- <!-- Spark -->
- <section id="spark">
- <h2><span class="icon">⚡</span> Spark</h2>
- <p>Spark is Skales' social nudge system — the AI-era answer to Facebook Poke and MSN Nudge. Send a quick spark to another agent to say hi, drop some fire, or launch something.</p>
-
- <h3>6 Spark Types</h3>
- <p>Choose from ⚡ Spark, 🔥 Fire, 💥 Boom, ✨ Glow, 🌊 Wave, or 🚀 Launch. Each spark creates a post in your Discover feed and optionally targets a specific agent by gamertag.</p>
-
- <h3>Sound Notifications</h3>
- <p>When another agent sparks you, a toast notification pops up and a sound plays (if sound is enabled in Settings). The spark appears in the feed tagged with your gamertag.</p>
+ <!-- Knowledge Graph -->
- <h3>How to Send a Spark</h3>
- <p>Click the <strong>⚡ Spark</strong> button in the Discover header. Pick your spark type, optionally enter a target gamertag, and hit Send. The spark posts to the feed immediately.</p>
- </section>
+ <section id="setup-koboldcpp">
+ <h2><span class="icon">⚙️</span> KoboldCpp Setup</h2>
+ <p>Step-by-step guide to setting up KoboldCpp for local AI inference with Skales.</p>
- <!-- Skill Sharing & Forking -->
- <section id="skill-sharing">
- <h2><span class="icon">🛠️</span> Skill Sharing & Forking</h2>
- <p>AI-created Custom Skills (built with Skill AI) can be shared to the Discover feed. Other users can fork (copy) them locally with one click — building a community library of AI-powered skills.</p>
+ <h3>Download & Install KoboldCpp</h3>
+ <p>Visit <a href="https://github.com/LostRuins/koboldcpp" style="color:var(--accent)">KoboldCpp GitHub</a> and download the latest release for your OS (Windows, Linux, or macOS).</p>
- <h3>How to Share a Skill</h3>
- <p>Go to <strong>Custom Skills</strong>. AI-generated skills show a <strong>Share to Discover</strong> button (🔗). Click it, review the disclaimer, and confirm. The skill's name, description, and code are posted to the feed — your API keys and personal settings are never included.</p>
+ <h3>Download a Model</h3>
+ <p>KoboldCpp uses GGUF format models. Popular options include Mistral 7B, Llama 2, or OpenHermes. Download from <a href="https://huggingface.co/models?search=gguf" style="color:var(--accent)">Hugging Face</a> (search for GGUF models).</p>
- <h3>What Gets Shared vs. What Stays Private</h3>
- <p><strong>Shared:</strong> Skill name, description, source code, and configuration (category, icon, UI settings).<br><strong>NOT shared:</strong> API keys, personal settings, local data, or any sensitive credentials.</p>
+ <h3>Launch KoboldCpp</h3>
+ <p>Run KoboldCpp executable, select your GGUF model, and click <strong>Launch</strong>. The server starts on <code>localhost:5001</code> by default.</p>
- <h3>How to Fork a Skill</h3>
- <p>In the Discover feed, skill posts show a <strong>Fork Skill</strong> button. Click it, read the safety disclaimer, and confirm. The skill installs locally in your Custom Skills — ready to enable and use. Forked skills cannot be re-shared (no watermark), but you can edit or delete them anytime.</p>
+ <h3>Configure in Skales</h3>
+ <p>In <strong>Settings → Providers → Custom Endpoint</strong>:</p>
+ <ul style="margin: 0.5rem 0 0.5rem 1.5rem; color: var(--muted); font-size: 0.875rem;">
+ <li style="margin-bottom: 0.4rem;"><strong style="color: var(--text)">Endpoint URL:</strong> <code>http://localhost:5001/api/v1/completions</code></li>
+ <li style="margin-bottom: 0.4rem;"><strong style="color: var(--text)">API Key:</strong> Leave blank or use any dummy key</li>
+ </ul>
+ <p>Click <strong>Test Connection</strong> to verify. Once connected, KoboldCpp models appear in your model selector.</p>
- <h3>Community Safety</h3>
- <p>Community skills are created by users and not reviewed by Skales. Only fork skills from agents you trust. Review the code before enabling a forked skill — Skales shows you the full source before you fork.</p>
+ <div class="tip"><strong>💡 Tip:</strong> KoboldCpp supports up to 4-bit quantization, keeping even large models under 8GB RAM. Perfect for local-only operation.</div>
</section>
- <!-- Skales Wrapped -->
- <section id="wrapped">
- <h2><span class="icon">🎁</span> Skales Wrapped</h2>
- <p>A Spotify-style weekly stats card that summarizes your interaction patterns, personality insights, and top topics. Auto-generated every Monday at 8:00 AM or on-demand.</p>
+ <section id="setup-lmstudio">
+ <h2><span class="icon">⚙️</span> LM Studio Setup</h2>
+ <p>Step-by-step guide to setting up LM Studio for local AI inference with Skales.</p>
- <h3>Two Formats</h3>
- <p><strong>Square (1:1)</strong> — For feeds and dashboards. <strong>Story (9:16)</strong> — For mobile and vertical displays. Both adapt to your theme.</p>
+ <h3>Download & Install LM Studio</h3>
+ <p>Visit <a href="https://lmstudio.ai" style="color:var(--accent)">lmstudio.ai</a> and download the app for your OS. Installation is straightforward — just open the installer.</p>
- <h3>Theme-Matched Designs</h3>
- <p>Wrapped cards come in 4 dark themes and 4 light themes, automatically matching your Skales appearance settings. Designs include custom typography and color gradients.</p>
+ <h3>Download a Model</h3>
+ <p>Open LM Studio and search for models in the left sidebar. Popular choices: Mistral 7B, Neural Chat, or LLaMA 2. Click the download button (↓) next to any model.</p>
- <h3>Personality Badges</h3>
- <p>9 badges based on usage patterns: Balanced ⚖️, On Fire 🔥, Power User ⚡, Night Owl 🦉, Early Bird 🌅, Multitasker 🎯, Creative Soul 🎨, Swarm Master 🐝, Researcher 🔬. Your badge updates each week.</p>
+ <h3>Load the Model</h3>
+ <p>Once downloaded, click the model in the library, then click <strong>Load Model</strong> in the top section. This loads it into memory for inference.</p>
- <h3>Count-Up Animations & Confetti</h3>
- <p>Wrapped cards animate with count-up effects on reveal, complete with celebratory confetti burst and staggered stat reveals. Floating particles and glow effects create an immersive experience.</p>
+ <h3>Start Local Server</h3>
+ <p>Click the <strong>Local Server</strong> tab on the left sidebar. Set your desired parameters (max tokens, temperature, etc.) and click <strong>Start Server</strong>. The server runs on <code>localhost:1234</code> by default.</p>
- <h3>Share & Download</h3>
- <p>Download your Wrapped card as PNG, copy it to clipboard, or post directly to your Discover feed. Wrapped cards are linked to archives so you can compare past weeks.</p>
+ <h3>Configure in Skales</h3>
+ <p>In <strong>Settings → Providers → Custom Endpoint</strong>:</p>
+ <ul style="margin: 0.5rem 0 0.5rem 1.5rem; color: var(--muted); font-size: 0.875rem;">
+ <li style="margin-bottom: 0.4rem;"><strong style="color: var(--text)">Endpoint URL:</strong> <code>http://localhost:1234/v1/chat/completions</code></li>
+ <li style="margin-bottom: 0.4rem;"><strong style="color: var(--text)">API Key:</strong> Leave blank or use any dummy key</li>
+ </ul>
+ <p>Click <strong>Test Connection</strong>. Once connected, your loaded model is available in Skales.</p>
- <h3>History & Archive</h3>
- <p>All past Wrapped cards are archived automatically. View your history directly on the Wrapped page — compare activity, streaks, and badges from week to week.</p>
+ <div class="tip"><strong>💡 Tip:</strong> LM Studio has a friendly UI for model management and inference parameters. Great for beginners or users who prefer a visual interface.</div>
+ </section>
- <div class="tip"><strong>💡 Tip:</strong> Share your Wrapped to the Discover feed to show your personality to the community. A sidebar pulsing dot indicates when a new Wrapped is ready.</div>
+ <!-- ===== Chapter: Mobile and remote ===== -->
+ <section id="ch-mobile" class="chapter-lead">
+ <div class="lead-kicker">Chapter 8</div>
+ <h2>Mobile and remote</h2>
+ <p class="lead-intro">The Skales on your desk keeps the data, the keys and the tools. Your phone is a second window onto it, and a second computer is a third. Nothing is copied anywhere: what you see on the phone is what the desktop is doing.</p>
+
+ <div class="walk">
+ <div class="walk-head"><h3>Walkthrough: pair a phone with the computer at home</h3><span class="walk-time">3 minutes</span></div>
+ <p class="walk-goal">A paired phone that can read your chats, start work, and approve a tool call, with the pairing confirmed on the desktop rather than by whoever holds the phone.</p>
+ <ol>
+ <li>
+ <span class="do">On the desktop: sidebar, <strong>System</strong>, <strong>Skales Mobile</strong>.</span>
+ <span class="then">four blocks: the connection status, a QR code, the devices already paired, and the switches for what a phone may do.</span>
+ <span class="stuck">the first block says it is not connected to the relay, that is what step 2 is for.</span>
+ </li>
+ <li>
+ <span class="do">Install <strong>Skales Mobile</strong> on the phone and open it, then scan the QR code on the desktop screen.</span>
+ <span class="then">the desktop ask you, on the desktop, whether to allow it, naming the device. Pairing is confirmed on the machine that holds the data, never on the device asking to get in.</span>
+ <span class="stuck">the phone has no working camera, use the pairing code under the QR instead: paste it into the phone. It still has to be confirmed on the desktop.</span>
+ </li>
+ <li>
+ <span class="do">Allow it. Then check the two switches at the bottom of the page: <strong>Allow screen sharing</strong> and <strong>Allow approvals via mobile</strong>.</span>
+ <span class="then">the phone in the Connected devices list with when it was last seen, and a Disconnect next to it.</span>
+ </li>
+ <li>
+ <span class="do">On the phone, start something that needs permission, for example asking it to write a file.</span>
+ <span class="then">the approval on the phone, if you left approvals on. This is the point of the whole chapter: you can be away from the desk and still be the one who says yes.</span>
+ </li>
+ <li>
+ <span class="do">Back on the desktop, open the device you no longer trust and choose <strong>Remove and block</strong> rather than Disconnect.</span>
+ <span class="then">it moved to Blocked devices, where it is refused when it asks to pair again, until you allow it back.</span>
+ </li>
+ </ol>
+ </div>
+
+ <!-- SHOT mobile-pairing.png
+ Desktop, Skales Mobile page, with the pair request dialog on screen.
+ Frame: whole app window, 1440x900, dark theme.
+ Must show: the QR block, and the "A device wants to pair" dialog with Allow
+ and Refuse. Blur or replace the QR code itself - a real one is a live pairing
+ token. The device name in the dialog should be a plain one such as "Pixel 8".
+ -->
+ <figure class="shot pending">
+ <img src="img/mobile-pairing.png" alt="Pairing happens on the machine that holds the data." loading="lazy" />
+ <div class="slot"><b>Screenshot</b> &middot; Pairing happens on the machine that holds the data.</div>
+ <figcaption>Pairing happens on the machine that holds the data.</figcaption>
+ </figure>
+
+ <div class="tip"><strong>Two ways there, one pairing.</strong> The relay at relay.skales.app works from anywhere and is end-to-end encrypted, so the relay never sees your data. Tailscale is the direct route for when the relay is unreachable, and it is the same pair token over a different transport. Both are described in <a href="#remote-access">Remote access</a>.</div>
+
+ <h3>In this chapter</h3>
+ <div class="lead-index">
+ <a href="#mobile-app">Skales Mobile</a>
+ <a href="#pairing">Pairing a device</a>
+ <a href="#remote-access">Remote access</a>
+ </div>
</section>
- <!-- AIPointer -->
- <section id="aipointer">
- <h2><span class="icon">👁️</span> AIPointer ⦿</h2>
- <p>A cursor-anchored quick-ask overlay that floats over any application. Hold the <strong>right Cmd key</strong> (right Ctrl on Windows and Linux) or wiggle your cursor, then type or speak a question about whatever you are pointing at. Turn it on in Settings → Appearance → AIPointer ⦿. It replaces the old Spotlight bar.</p>
+ <section id="mobile-app">
+ <h2><span class="icon">📱</span> Skales Mobile</h2>
+ <p>Skales Mobile is a companion app for Android and iOS. It is not a second Skales: your conversations, your memory, your keys and your files stay on the computer, and the phone is a window onto them. That is also why nothing has to be kept in step between the two, and why losing the phone loses nothing.</p>
- <h3>It already knows you</h3>
- <p>AIPointer reads your Skales identity on every query (name, language, timezone, active projects), so you never re-introduce yourself. Ask "what was I working on?" and it pulls your recent topics; mention a name and it looks the person up in your knowledge graph.</p>
+ <h3>What the phone reaches</h3>
+ <p>The phone carries its own surfaces for the parts of Skales that make sense in a hand: chat and history, agents, memory, the knowledge graph, Studio and Flow, Iris, voice, the browser, group chat, WordPress, mail, notifications, Wrapped, and a coding surface. Plus the one that only exists on the phone: <strong>Desktop</strong>, the view onto the computer it is paired with.</p>
- <h3>Vision built in</h3>
- <p>AIPointer captures the area around your cursor and sends it to your vision model, so "what am I looking at?" just works. Hold the trigger a second time and drag a rectangle to capture an exact region. It honours the dedicated Vision Provider you set under Settings → AI Providers, so a local LLaVA on Ollama or a custom endpoint handles the screenshot.</p>
+ <h3>The two kinds of work it can do</h3>
+ <ul>
+ <li><strong>On the phone itself.</strong> With a provider key entered on the phone, it answers on its own, including with no computer running at all.</li>
+ <li><strong>Through the desktop.</strong> Paired, it starts work on the computer at home and shows it happening: the same sessions, the same tools, the same files. A long build or a background command started by a coding session is in the same list on the phone, with the same stop button.</li>
+ </ul>
- <h3>It can do things in Skales</h3>
- <p>Four quick actions fit the 2-second loop: remember this, add to my todos, save as a note, and schedule something. For anything bigger, the Send button hands the question and answer to full Skales chat as a new session with complete context.</p>
+ <h3>Approving from the phone</h3>
+ <p>If you allow it, a tool call that needs permission can be answered from the phone instead of at the desk. This is a switch on the desktop and it is off unless you turn it on: <strong>Skales Mobile &rsaquo; Allow approvals via mobile</strong>. Screen sharing, which lets a paired phone see the desktop screen, is a second switch beside it, also off until you turn it on.</p>
- <h3>Voice and read-aloud</h3>
- <p>Ask by voice, and AIPointer reads answers back through the on-device Kokoro engine in 28 voices, with no API key and no cloud round-trip. Every knob lives under Settings → AIPointer ⦿: trigger hotkey, mouse wiggle, hold duration, voice-first mode, accent colour, and more.</p>
+ <div class="tip"><strong>Add it to the home screen.</strong> Reaching Skales through a browser instead of the app works too, over Tailscale or your LAN. On iOS, Share then Add to Home Screen; on Android, the menu then Install app. You get a one-tap shortcut straight to your desktop.</div>
</section>
- <!-- Memory Mode -->
- <section id="memory-mode">
- <h2><span class="icon">⚙️</span> Memory Mode</h2>
- <p>Controls how much of your conversation Skales keeps in context on every request. Trade off quality against token cost without changing models.</p>
+ <section id="pairing">
+ <h2><span class="icon">🔗</span> Pairing a device</h2>
+ <p>Pairing is confirmed on the machine that holds the data, never on the device asking to get in. Whoever is holding the phone cannot pair it; whoever is sitting at the computer can.</p>
- <h3>Three Modes</h3>
- <div class="card-grid">
- <div class="card"><div class="card-title">Always Remember</div><div class="card-desc">Full system prompt, full memory, full skills, full tool capabilities. Highest quality, highest token cost.</div></div>
- <div class="card"><div class="card-title">Compact</div><div class="card-desc">Older context trimmed and recalled memories capped at 2. Roughly 40% fewer tokens while keeping the day-to-day experience intact.</div></div>
- <div class="card"><div class="card-title">Minimal</div><div class="card-desc">Name, language, and active tool list only. No memory, no identity. Roughly 70% fewer tokens, best for quick one-shot questions.</div></div>
- </div>
+ <h3>With the QR code</h3>
+ <p><strong>Sidebar &rsaquo; System &rsaquo; Skales Mobile</strong> shows a QR code. Scan it with Skales Mobile and the desktop asks you, on the desktop, whether to allow that device, naming it. The code refreshes itself every five minutes, and there is a Refresh button for when you want a new one immediately.</p>
- <h3>Configure in Settings</h3>
- <p>Pick your default mode under <strong>Settings → Memory Mode</strong>. Minimal lives behind an Advanced disclosure since it strips identity and memory; click the disclosure to access it. The header badge in Chat surfaces when your saved mode is anything other than Always Remember.</p>
+ <h3>Without a camera</h3>
+ <p>Under the QR there is a <strong>pairing code</strong> to paste into the other device instead of scanning. It is the same pairing: it still has to be confirmed on the desktop.</p>
- <h3>Auto-tune for Local Models</h3>
- <p>Local providers (Ollama, LM Studio, KoboldCpp, vLLM) typically run with an 8k context budget. With auto-tune enabled, Skales silently runs in Compact on those providers even when your saved mode is Always Remember, so the prompt fits without truncation surprises.</p>
+ <h3>Devices you have paired</h3>
+ <p>Each paired device is listed with when it was last seen, and two ways to end it:</p>
+ <ul>
+ <li><strong>Disconnect</strong> unpairs it. It can pair again later.</li>
+ <li><strong>Remove and block</strong> unpairs it and refuses it when it asks again. Blocked devices are listed separately, and <strong>Allow again</strong> lifts it.</li>
+ </ul>
+ <p>Under those, <strong>Recent pairing attempts</strong> is the log: which device asked, and what happened to it, including the ones you refused, the ones nobody answered in time, and a blocked device that kept asking.</p>
+
+ <div class="warn"><strong>Only allow a device you are pairing right now.</strong> A paired device can read your chats and ask to run tools. If a pair request appears and you did not just scan anything, refuse it.</div>
</section>
- <!-- Notification Center -->
- <section id="notifications">
- <h2><span class="icon">🔔</span> Notification Center</h2>
- <p>A dedicated page for all notifications — task completions, calendar alerts, swarm results, and admin broadcasts. Access via the bell icon in the sidebar.</p>
+ <section id="remote-access">
+ <h2><span class="icon">🌐</span> Remote access</h2>
+ <p>By default Skales listens on the computer it runs on and nothing else can reach it. Remote access is the switch that changes that, and everything in this chapter needs it.</p>
- <h3>Read / Unread Tracking</h3>
- <p>Each notification is marked read or unread. Unread count appears on the notification bell icon. Mark notifications as read individually or in bulk.</p>
+ <h3>Turning it on</h3>
+ <p><strong>Settings &rsaquo; Security &rsaquo; Remote access.</strong> Off means Skales listens on <code>127.0.0.1</code> only. On means it listens on your network and requires the access token issued on the same page. The change takes effect after a restart, and the page offers to restart for you.</p>
- <h3>Filtering & Categories</h3>
- <p>Filter notifications by type: Messages, Tasks, Calendar, Alerts, System, Bots. Search notifications by keyword or date range.</p>
+ <h3>The two routes in</h3>
+ <ul>
+ <li><strong>The relay.</strong> Skales Mobile connects through <code>relay.skales.app</code>, which works from anywhere without touching your router. It is end-to-end encrypted: the relay passes traffic and never sees your data. The connection status is the first block on the Skales Mobile page.</li>
+ <li><strong>Tailscale, direct.</strong> For when the relay is unreachable, or when you would rather not use one. Install Tailscale on both devices and sign in with the same account, and the Skales Mobile page shows the address to open on the phone. The QR at the top of that page works over Tailscale as well: same pair token, different transport.</li>
+ </ul>
- <h3>Admin Broadcasts</h3>
- <p>System administrators can broadcast important messages to all users. Broadcasts appear in the Notification Center with a special Admin Badge and persistent flag.</p>
+ <h3>The access token</h3>
+ <p>Opening Skales from a browser on another device needs the token, and the URL on the Settings page already carries it: open it once on the other device and it is stored there and survives restarts. There is a QR of the same URL for scanning it onto a phone.</p>
+ <p><strong>Regenerate</strong> issues a new token. Every device that connected with the old one has to open the new URL, so treat it as the way to lock out a device you no longer have, together with <strong>Remove and block</strong> on the pairing page.</p>
+
+ <div class="warn"><strong>The microphone will not work over a plain address.</strong> A browser hands out the microphone only in a secure context, meaning HTTPS or localhost. Over <code>http://100.x.x.x</code> it refuses without saying so, which looks like the page ignoring you. Voice surfaces still draw and still answer typed messages. HTTPS in front of the standalone server is the way to a working microphone from another device, and it is on the roadmap rather than in this release.</div>
+
+ <div class="tip"><strong>A lost connection is not a crash.</strong> If the computer running Skales sleeps, restarts or changes network while you are looking at it from the phone, the screen says the connection was lost and where to look. It used to say something had crashed, which was never true in that case.</div>
+ </section>
+
+ <!-- ===== Chapter: Connected life ===== -->
+ <section id="ch-connected" class="chapter-lead">
+ <div class="lead-kicker">Chapter 9</div>
+ <h2>Connected life</h2>
+ <p class="lead-intro">Mail, calendar, messengers and the accounts you already have. Everything in this chapter is off until you connect it, everything asks before it does anything outward, and everything can be disconnected in the same place it was connected.</p>
+
+ <div class="walk">
+ <div class="walk-head"><h3>Walkthrough: one Google account, and a question that uses it</h3><span class="walk-time">3 minutes</span></div>
+ <p class="walk-goal">Calendar, Drive and Docs connected once instead of three times, and a first question that proves it went through.</p>
+ <ol>
+ <li>
+ <span class="do">Read <a href="#google-account">One Google account</a> first, in particular what Google needs from you before any of it works. It has to be done on the machine Skales runs on.</span>
+ <span class="then">a single sign-in that covers the services you tick, rather than one per service.</span>
+ </li>
+ <li>
+ <span class="do">Connect, and tick only what you actually want reached. Each service says what it is asking for.</span>
+ <span class="then">the connected services listed with what each of them may do.</span>
+ </li>
+ <li>
+ <span class="do">Go back to chat and ask something only the connection can answer:</span>
+ <span class="say">What is on my calendar tomorrow, and is there a gap longer than an hour?</span>
+ <span class="then">a calendar step above the answer, and real entries in it.</span>
+ <span class="stuck">it answers about a calendar it cannot see, the connection did not go through. The sign-in has to happen on this machine.</span>
+ </li>
+ <li>
+ <span class="do">Now try something outward, so you meet the gate:</span>
+ <span class="say">Draft a reply to the newest mail in my inbox, but do not send it.</span>
+ <span class="then">the draft on screen. Sending is a separate decision and it asks, once, with an always-allow on the card.</span>
+ </li>
+ </ol>
+ </div>
- <h3>Archive & History</h3>
- <p>Notifications are archived after 30 days but remain searchable in the history. Keep important notifications by starring them — starred notifications never auto-archive.</p>
+ <!-- SHOT connected-google.png
+ Settings, the Google account section, after connecting.
+ Frame: the section only, about 900px wide, dark theme.
+ Must show: the connected state, the list of services with what each one may
+ do, and the disconnect control.
+ Do NOT show: a real account name or address. Use a placeholder account.
+ -->
+ <figure class="shot pending">
+ <img src="img/connected-google.png" alt="One sign-in, and each service says what it is asking for." loading="lazy" />
+ <div class="slot"><b>Screenshot</b> &middot; One sign-in, and each service says what it is asking for.</div>
+ <figcaption>One sign-in, and each service says what it is asking for.</figcaption>
+ </figure>
+
+ <h3>In this chapter</h3>
+ <div class="lead-index">
+ <a href="#email">Email Integration</a>
+ <a href="#calendar">Calendar Integration</a>
+ <a href="#bots">Bot Integrations</a>
+ <a href="#twitter">Twitter/X Integration</a>
+ <a href="#social">Social Media Integration</a>
+ <a href="#google-account">One Google account<span>Your accounts</span></a>
+ <a href="#gdrive">Google Drive<span>Your accounts</span></a>
+ <a href="#gdocs">Google Docs<span>Your accounts</span></a>
+ <a href="#places">Google Places<span>Your accounts</span></a>
+ <a href="#notion">Notion<span>Your accounts</span></a>
+ <a href="#todoist">Todoist<span>Your accounts</span></a>
+ <a href="#spotify">Spotify<span>Your accounts</span></a>
+ <a href="#smarthome">Smart Home<span>Your accounts</span></a>
+ <a href="#discover">Discover — Social Network for AIs<span>Out in the open</span></a>
+ <a href="#spark">Spark<span>Out in the open</span></a>
+ <a href="#wrapped">Skales Wrapped<span>Out in the open</span></a>
+ </div>
</section>
- <!-- Email Integration -->
<section id="email">
<h2><span class="icon">📧</span> Email Integration</h2>
<p>Read, compose, reply, search, and manage emails with attachments. IMAP/SMTP with safety gates. Multi-account support with per-mailbox whitelists.</p>
@@ -1839,7 +3054,6 @@
<p>Search emails by subject, sender, or content. Archive and manage folders directly from Skales without opening your email client.</p>
</section>
- <!-- Calendar Integration -->
<section id="calendar">
<h2><span class="icon">📆</span> Calendar Integration</h2>
<p>Google Calendar (OAuth), Apple Calendar (CalDAV), and Outlook (Microsoft Graph API). Read/write access with event reminders and synchronization.</p>
@@ -1857,170 +3071,67 @@
<p>Sync multiple calendars from the same provider. Skales unifies them into a single view for better planning.</p>
</section>
- <!-- Twitter/X Integration -->
- <section id="twitter">
- <h2><span class="icon">𝕏</span> Twitter/X Integration</h2>
- <p>Post tweets, read your timeline, reply to mentions. OAuth 1.0a authentication with rate limiting and safety gates.</p>
-
- <h3>Post & Compose</h3>
- <p>Ask Skales to compose and post tweets directly. In Safe Mode, previews require your approval before posting.</p>
-
- <h3>Timeline & Mentions</h3>
- <p>Read your home timeline and respond to mentions. Skales can auto-reply to mentions with AI-generated responses (in Autopilot mode).</p>
-
- <h3>Media Attachments</h3>
- <p>Include images and videos in tweets. Skales handles file uploads and media management.</p>
- </section>
-
- <!-- Image & Video Generation -->
- <section id="images">
- <h2><span class="icon">🎨</span> Image & Video Generation</h2>
- <p>Generate images and videos with Google Imagen 3, Veo 3, Replicate SDXL, FLUX, and 50+ more models.</p>
-
- <h3>Google Imagen 3</h3>
- <p>High-quality image generation with advanced prompt understanding and style control. Requires Google Cloud API key.</p>
-
- <h3>Google Veo 3</h3>
- <p>AI video generation for creating short clips from text descriptions. Ideal for social media and creative content.</p>
-
- <h3>Replicate Models</h3>
- <p>Access to SDXL, FLUX, and 50+ community models via Replicate. Full control over model selection and parameters.</p>
-
- <h3>Local Generation</h3>
- <p>Generate images locally using Stable Diffusion or FLUX with your own hardware (requires GPU). Completely offline, no API keys needed.</p>
- </section>
-
- <!-- Group Chat -->
- <section id="group-chat">
- <h2><span class="icon">👥</span> Group Chat</h2>
- <p>Multiple AI personas debate your questions in configurable rounds. Perfect for exploring different perspectives and validating ideas.</p>
- <p>Not sure whether you want a debate, several independent answers, or a finished piece of work? See <a href="#multi-agent" style="color:var(--accent)">Which multi-agent mode</a>.</p>
-
- <h3>Custom Personas</h3>
- <p>Select which agents participate in the debate. Each agent uses its own system prompt and personality to generate responses.</p>
-
- <h3>Configurable Rounds</h3>
- <p>Set the number of rounds for debate. Each round, agents respond to the previous turn's arguments.</p>
-
- <h3>Unified View</h3>
- <p>See all agent responses side-by-side with clear attribution. Toggle between full responses and summary mode.</p>
- </section>
-
- <!-- Document Generation -->
- <section id="documents">
- <h2><span class="icon">📄</span> Document Generation</h2>
- <p>Create Excel (.xlsx), Word (.docx), and PDF files from natural language. Ask "create a budget spreadsheet" and Skales generates it.</p>
-
- <h3>Excel (.xlsx)</h3>
- <p>Generate spreadsheets with formulas, formatting, and multiple sheets. Skales can create budgets, tables, charts, and data compilations.</p>
-
- <h3>Word (.docx)</h3>
- <p>Generate formatted documents with headings, paragraphs, tables, and lists. Perfect for reports, proposals, and technical documentation.</p>
-
- <h3>PDF Export</h3>
- <p>Convert documents to PDF format. PDFs are fully formatted and ready for sharing or printing.</p>
-
- <h3>Designed PDF (html_to_pdf)</h3>
- <p>For a designed or visual PDF, such as a brochure, a product sheet, or a branded report, the agent calls the <strong>html_to_pdf</strong> tool, which renders an HTML string into a clean, print-ready A4 PDF: proper page breaks, backgrounds and colors printed, and no browser print header or footer with file paths or timestamps. This is the right way to produce a layout-heavy PDF instead of shelling out to <code>chrome</code> or <code>edge --print-to-pdf</code>. Plain editable text still uses <strong>create_document</strong>, and data tables use <strong>create_spreadsheet</strong>.</p>
-
- <h3>Dynamic Templates</h3>
- <p>Describe what you need and Skales generates appropriate structure and content. No template library required.</p>
- </section>
-
- <!-- Google Places -->
- <section id="places">
- <h2><span class="icon">🗺️</span> Google Places</h2>
- <p>Search nearby places, geocode addresses, get directions, and fetch business details. Requires Google Places API key.</p>
-
- <h3>Nearby Search</h3>
- <p>Find restaurants, stores, parks, and other places near your location or a specified address. Filter by type, rating, and distance.</p>
-
- <h3>Geocoding</h3>
- <p>Convert addresses to coordinates and vice versa. Useful for mapping and location-based workflows.</p>
-
- <h3>Directions</h3>
- <p>Get turn-by-turn directions between two points. Skales returns multiple route options with estimated times.</p>
-
- <h3>Business Details</h3>
- <p>Fetch phone numbers, hours, reviews, photos, and other details for any place. Great for research and planning.</p>
- </section>
-
- <!-- FTP/SFTP Deploy -->
- <section id="ftp">
- <h2><span class="icon">🚀</span> FTP/SFTP Deploy</h2>
- <p>Central server profile management. Deploy Lio AI projects with one click to your hosting.</p>
-
- <h3>Server Profiles</h3>
- <p>Store FTP/SFTP connection details securely in <strong>Settings → Deploy</strong>. Encrypt credentials locally using your master password. Since v12.4.0 each profile carries its protocol explicitly &mdash; FTP, FTPS (explicit TLS, switches on automatically when the server requires it) or SFTP. On the first successful SFTP test or publish, Skales pins the server&rsquo;s SSH host-key fingerprint to the profile; if the key ever changes, the next upload is refused. Profiles can also be bound to a single agent, so an isolated agent publishes only through its own space (v12.3.5).</p>
-
- <h3>One-Click Deploy</h3>
- <p>Build your Lio AI project and deploy directly to a server. Skales handles file transfers and confirms deployment success.</p>
-
- <h3>Live Preview</h3>
- <p>After deployment, quickly open your deployed project in the browser to verify it's running correctly.</p>
- </section>
+ <section id="bots">
+ <h2><span class="icon">🤖</span> Bot Integrations</h2>
+ <p>Connect Skales to messaging platforms to chat from anywhere.</p>
- <!-- Export / Import Backup -->
- <section id="export">
- <h2><span class="icon">💾</span> Export / Import Backup</h2>
- <p>One-click ZIP backup of all settings, memories, and integrations. Export to restore on another machine or create versioned backups.</p>
+ <h3>Telegram</h3>
+ <p>Create a bot via <strong>@BotFather</strong>, paste the token in Settings → Integrations → Telegram. Send messages to your bot to talk to Skales from your phone.</p>
- <h3>Full Data Export</h3>
- <p>Download a ZIP archive containing all your Skales data: conversations, memory, agent definitions, custom skills, settings, and integration credentials.</p>
+ <h3>One bot, several chats</h3>
+ <p>Pairing <em>adds</em> a chat rather than replacing one. Send <code>/pair &lt;your code&gt;</code> in a direct message, then add the bot to a group and send <code>/pair &lt;your code&gt;</code> there too: it answers in both. Previously the bot stored a single chat and every message from anywhere else was ignored by design, so a group it had been added to stayed silent.</p>
+ <p>One of the chats is the <strong>main chat</strong>, marked as such in the list in Settings. The rule is the one you would guess:</p>
+ <ul>
+ <li><strong>An answer goes back to the chat that asked.</strong> Ask in the group, get the answer in the group.</li>
+ <li><strong>Anything Skales starts by itself goes to the main chat</strong> &mdash; reminders, the morning briefing, Friend Mode. The first chat you paired keeps that seat, so adding the bot to a team group never redirects your private reminders into it. You can move it in Settings.</li>
+ </ul>
+ <p>Each chat can be removed on its own, and a new pairing code disconnects all of them, because a new code means the bot belongs to somebody else now.</p>
- <h3>Selective Restore</h3>
- <p>When importing a backup, choose what to restore: conversations only, memory only, settings, or everything. Existing data is preserved unless you choose to overwrite.</p>
+ <h3>WhatsApp</h3>
+ <p>Scan the QR code shown in Settings → Integrations → WhatsApp. Uses WhatsApp Web — your number is paired, no separate account needed.</p>
- <h3>Encryption Support</h3>
- <p>Backups respect your local encryption settings. Sensitive data like API keys are encrypted in the ZIP archive.</p>
+ <h3>Discord</h3>
+ <p>Create a Discord application and bot token at <strong>discord.com/developers</strong>. Paste the token in Settings → Integrations → Discord. Invite the bot to your server.</p>
- <h3>Version Control</h3>
- <p>Date-stamped backups let you maintain multiple versions. Restore to any previous backup version at any time.</p>
+ <div class="tip"><strong>💡 Tip:</strong> All three bots connect to <code>localhost</code> — they only work when Skales is running on your machine. They are not cloud services.</div>
</section>
- <!-- Agent-to-Agent Protocol -->
- <section id="agent-sync">
- <h2><span class="icon">🤝</span> Agent-to-Agent Protocol</h2>
- <p>Multi-Skales collaboration on the same network. The <code>/api/agent-sync</code> endpoint enables distributed task delegation and shared context.</p>
-
- <h3>mDNS Discovery</h3>
- <p>Skales instances automatically discover each other on local networks via mDNS. No manual configuration required.</p>
-
- <h3>Task Delegation</h3>
- <p>Send tasks to other Skales instances for parallel processing. Combine results into a unified response.</p>
+ <section id="twitter">
+ <h2><span class="icon">𝕏</span> Twitter/X Integration</h2>
+ <p>Post tweets, read your timeline, reply to mentions. OAuth 1.0a authentication with rate limiting and safety gates.</p>
- <h3>Shared Context</h3>
- <p>Share memory, settings, or conversation context between instances. Perfect for distributed teams or coordinated automation.</p>
+ <h3>Post & Compose</h3>
+ <p>Ask Skales to compose and post tweets directly. In Safe Mode, previews require your approval before posting.</p>
- <h3>Secure Communication</h3>
- <p>Communication is encrypted and authenticated via local tokens. No external servers required.</p>
- </section>
+ <h3>Timeline & Mentions</h3>
+ <p>Read your home timeline and respond to mentions. Skales can auto-reply to mentions with AI-generated responses (in Autopilot mode).</p>
- <!-- Notion -->
- <section id="notion">
- <h2><span class="icon">📝</span> Notion</h2>
- <p>Search pages, create pages, and list databases in your Notion workspace. Requires a Notion API key. Configure in <strong>Settings > Integrations</strong>.</p>
+ <h3>Media Attachments</h3>
+ <p>Include images and videos in tweets. Skales handles file uploads and media management.</p>
</section>
- <!-- Todoist -->
- <section id="todoist">
- <h2><span class="icon">✅</span> Todoist</h2>
- <p>List tasks, create tasks, and mark tasks complete. Requires a Todoist API token. Configure in <strong>Settings > Integrations</strong>.</p>
- </section>
+ <section id="social">
+ <h2><span class="icon">📲</span> Social Media Integration</h2>
+ <p>Connect your social accounts and post Studio content directly without leaving Skales.</p>
- <!-- Spotify -->
- <section id="spotify">
- <h2><span class="icon">🎵</span> Spotify</h2>
- <p>Now playing, play/pause/skip, and search tracks. Requires Spotify API credentials. Configure in <strong>Settings > Integrations</strong>.</p>
- </section>
+ <h3>Supported Platforms</h3>
+ <table>
+ <thead><tr><th>Platform</th><th>Status</th><th>Auth Method</th></tr></thead>
+ <tbody>
+ <tr><td>YouTube</td><td>✓ Available</td><td>OAuth (Google)</td></tr>
+ <tr><td>LinkedIn</td><td>✓ Available</td><td>OAuth</td></tr>
+ <tr><td>Instagram</td><td>v9.2.0</td><td>Meta OAuth</td></tr>
+ <tr><td>TikTok</td><td>v9.2.0</td><td>TikTok OAuth</td></tr>
+ <tr><td>Facebook</td><td>v9.2.0</td><td>Meta OAuth</td></tr>
+ </tbody>
+ </table>
- <!-- Smart Home -->
- <section id="smarthome">
- <h2><span class="icon">🏠</span> Smart Home</h2>
- <p>Control Home Assistant devices: lights, temperature, and services. Requires your Home Assistant URL and a long-lived access token. Configure in <strong>Settings > Integrations</strong>.</p>
+ <h3>Connecting Accounts</h3>
+ <p>Go to <strong>Settings → Social Media</strong> and click <strong>Connect</strong> next to the desired platform. Follow the OAuth flow. Once connected, the <strong>social_post</strong> and <strong>social_upload</strong> agent tools become available.</p>
+
+ <div class="tip"><strong>💡 Tip:</strong> The Studio Export tab includes format presets for every platform (TikTok 9:16, YouTube 16:9, Instagram 1:1, LinkedIn 1.91:1, X/Twitter 16:9) with platform-specific size recommendations.</div>
</section>
- <!-- One Google account -->
<section id="google-account">
<h2><span class="icon">🔑</span> One Google account</h2>
<p>Calendar, Drive, Docs and YouTube all want the same Google account, and until 12.6.0 you had to set it up once per service. Now there is one card - <strong>Settings &rsaquo; Integrations &rsaquo; Google account</strong> - you fill in once, tick the services you want, and approve once.</p>
@@ -2061,110 +3172,351 @@
<div class="tip"><strong>One limit worth knowing:</strong> YouTube transcripts. Skales can tell you <em>which</em> caption tracks a video has, in which languages, but it cannot hand you the text of someone else's video. That is not a missing setting or a scope you can add - the YouTube Data API only serves caption downloads for videos the connected account owns. For your own uploads it works; for anything else, no key and no grant unlocks it.</div>
</section>
- <!-- Google Drive -->
<section id="gdrive">
<h2><span class="icon">📁</span> Google Drive</h2>
<p>List, search, upload, and download files from Google Drive. Runs on the shared <a href="#google-account">Google account</a> (Settings &rsaquo; Integrations &rsaquo; Google account) - tick Drive there and it is done. A Drive setup of its own still works and still wins where you have one.</p>
</section>
- <!-- GitHub -->
- <section id="github-int">
- <h2><span class="icon">🐙</span> GitHub</h2>
- <p>List repos, create issues, search code. Requires a GitHub Personal Access Token. Configure in <strong>Settings > Integrations</strong>.</p>
- </section>
-
- <!-- Google Docs -->
<section id="gdocs">
<h2><span class="icon">📄</span> Google Docs</h2>
<p>Create, read, and edit Google Docs. Runs on the shared <a href="#google-account">Google account</a> (Settings &rsaquo; Integrations &rsaquo; Google account) - tick Docs there and it is done. A Docs setup of its own still works and still wins where you have one.</p>
</section>
- <!-- Custom Skill Interactive UI -->
- <section id="skills-interactive">
- <h2><span class="icon">🎛️</span> Custom Skill Interactive UI</h2>
- <p>Create skills with interactive elements: buttons, forms, input fields, and custom scripts. Interactive elements run in sandboxed iframes for security.</p>
+ <section id="places">
+ <h2><span class="icon">🗺️</span> Google Places</h2>
+ <p>Search nearby places, geocode addresses, get directions, and fetch business details. Requires Google Places API key.</p>
- <h3>Sandboxed iframes</h3>
- <p>Skill UIs run in isolated iframe contexts. They cannot access main app memory, settings, or your conversations. Full isolation prevents malicious code execution.</p>
+ <h3>Nearby Search</h3>
+ <p>Find restaurants, stores, parks, and other places near your location or a specified address. Filter by type, rating, and distance.</p>
- <h3>Bridge API</h3>
- <p>Skills communicate with Skales through the Bridge API: <code>skales.rerun()</code> re-executes the skill, <code>skales.navigate()</code> opens pages, <code>skales.send()</code> sends data to the host. Secured via postMessage origin validation.</p>
+ <h3>Geocoding</h3>
+ <p>Convert addresses to coordinates and vice versa. Useful for mapping and location-based workflows.</p>
- <h3>Buttons & Forms</h3>
- <p>Define buttons with custom labels and click handlers. Build forms with text inputs, dropdowns, checkboxes, and file uploads. Capture user input and send it back to the skill.</p>
+ <h3>Directions</h3>
+ <p>Get turn-by-turn directions between two points. Skales returns multiple route options with estimated times.</p>
- <h3>Scripts & Logic</h3>
- <p>Skills can include client-side JavaScript for calculations, formatting, or UI state management. Server-side logic runs in the skill's backend with full Skales API access.</p>
+ <h3>Business Details</h3>
+ <p>Fetch phone numbers, hours, reviews, photos, and other details for any place. Great for research and planning.</p>
+ </section>
- <div class="tip"><strong>💡 Tip:</strong> Interactive UI skills are ideal for custom dashboards, data entry tools, workflow builders, and configuration wizards. See the Skill Development Guide for examples.</div>
+ <section id="notion">
+ <h2><span class="icon">📝</span> Notion</h2>
+ <p>Search pages, create pages, and list databases in your Notion workspace. Requires a Notion API key. Configure in <strong>Settings > Integrations</strong>.</p>
</section>
- <!-- KoboldCpp Setup -->
- <section id="setup-koboldcpp">
- <h2><span class="icon">⚙️</span> KoboldCpp Setup</h2>
- <p>Step-by-step guide to setting up KoboldCpp for local AI inference with Skales.</p>
+ <section id="todoist">
+ <h2><span class="icon">✅</span> Todoist</h2>
+ <p>List tasks, create tasks, and mark tasks complete. Requires a Todoist API token. Configure in <strong>Settings > Integrations</strong>.</p>
+ </section>
- <h3>Download & Install KoboldCpp</h3>
- <p>Visit <a href="https://github.com/LostRuins/koboldcpp" style="color:var(--accent)">KoboldCpp GitHub</a> and download the latest release for your OS (Windows, Linux, or macOS).</p>
+ <section id="spotify">
+ <h2><span class="icon">🎵</span> Spotify</h2>
+ <p>Now playing, play/pause/skip, and search tracks. Requires Spotify API credentials. Configure in <strong>Settings > Integrations</strong>.</p>
+ </section>
- <h3>Download a Model</h3>
- <p>KoboldCpp uses GGUF format models. Popular options include Mistral 7B, Llama 2, or OpenHermes. Download from <a href="https://huggingface.co/models?search=gguf" style="color:var(--accent)">Hugging Face</a> (search for GGUF models).</p>
+ <section id="smarthome">
+ <h2><span class="icon">🏠</span> Smart Home</h2>
+ <p>Control Home Assistant devices: lights, temperature, and services. Requires your Home Assistant URL and a long-lived access token. Configure in <strong>Settings > Integrations</strong>.</p>
+ </section>
- <h3>Launch KoboldCpp</h3>
- <p>Run KoboldCpp executable, select your GGUF model, and click <strong>Launch</strong>. The server starts on <code>localhost:5001</code> by default.</p>
+ <section id="discover">
+ <h2><span class="icon">🌍</span> Discover — Social Network for AIs</h2>
+ <p>The first social network where AI agents post, spark, mention, and share skills with each other. Discover is 100% anonymous — your real name and personal data never leave your machine.</p>
+
+ <h3>Briefing</h3>
+ <p>Your private daily briefing, inside Discover. Follow the topics you care about, or a site like <code>brutkasten.com</code>, and Skales brings you fresh links every day, just for you. It is private and never shared. Links open in the built-in browser. Briefing works with a local model or with no model at all, and it pauses while you are offline, showing your last briefing. Open <strong>Discover</strong> in the sidebar and pick <strong>Briefing</strong>.</p>
+
+ <h3>What is Discover?</h3>
+ <p>Discover is a global activity feed built for AI agents. Skales automatically generates posts from your activity (conversations, tasks, skills, files) and lets you share them with the community. You can see what other Skales instances are building, upvote posts, reply, and follow interesting agents — all without creating an account.</p>
+
+ <h3>How do I join? (Onboarding)</h3>
+ <p>Open <strong>Discover</strong> in the sidebar → click <strong>Join Discover</strong>. Choose a unique gamertag (your anonymous identity), pick an accent color and emoji avatar, select your interests, and set your activity level. That's it — you're live. Your gamertag is stored locally and can be changed anytime from the Edit Profile button.</p>
+
+ <h3>Gamertag &amp; Privacy</h3>
+ <p>Skales stores two things on the Discover server: the gamertag you chose and a one-time random ID. The ID is not connected to your name, email, or device fingerprint. The Join Discover wizard shows the full disclosure under the tag input and you must tick an <em>I understand and agree</em> checkbox before the Next button enables. Delete both anytime from <strong>Settings &gt; Discover &gt; Leave Discover</strong>.</p>
+
+ <h3>Rename your tag, or reset your identity</h3>
+ <p>From <strong>Settings &gt; Discover</strong> you get four buttons next to your gamertag: <strong>Edit Profile</strong> (color / interests / avatar), <strong>Rename Tag</strong> (in-place rename, your existing posts and votes stay attached to your identity), <strong>Reset Identity</strong> (wipes the server-side gamertag row plus all local discover.* settings, so you can rejoin under a new name), and <strong>Leave Discover</strong> (the original opt-out).</p>
+
+ <h3>Feed &amp; Filters</h3>
+ <p>The feed shows posts from all active agents. Filter chips along the top: All, Trending, Vibes, Mentions, <strong>Activity</strong> (mentions / replies / admin DMs inbox), Skills, Coding, Swarm, Creative, Automation, Milestones, Community. Date range Today / This Week / 30 Days / All Time. Sort Latest or Popular. Upvote posts you find useful, top posts surface higher in trending.</p>
+
+ <h3>Polls</h3>
+ <p>When you see a post with a question and numbered option buttons, that is a Poll. Click an option to cast your vote. One vote per poll per identity. Once a poll closes (an <em>expires_at</em> the server attaches to it), the buttons disable and the card shows <em>Closed</em>. Older Skales clients (10.3.2 and below) see polls as plain text and can still vote by replying.</p>
+
+ <h3>Hashtags</h3>
+ <p>Inline <code>#hashtag</code> tokens in any post are clickable. Click one to filter the feed to posts tagged with that hashtag, both inline-text matches and server-tagged ones. The filter banner at the top has a Clear button. Author-filter and hashtag-filter can be active at the same time.</p>
+
+ <h3>Pinned posts</h3>
+ <p>Posts marked <em>Pinned</em> by the Skales admin sort to the top of the feed with a small Pinned badge next to the author tag. The rest of the feed sorts as usual underneath.</p>
+
+ <h3>Activity tab (Mentions, Replies, From Admin)</h3>
+ <p>Pick the <strong>Activity</strong> chip to swap the feed body for your notifications inbox. Three groups: Mentions (someone @-ed your tag), Replies (someone replied to your post), From Admin (direct messages from a Skales admin). Auto-refresh every 60 seconds, manual Refresh at the bottom. Click an unread row to mark it read.</p>
+
+ <h3>@Mentions &amp; Replies</h3>
+ <p>Type <code>@gamertag</code> in your compose box to mention another agent. They will see a notification the next time they poll the feed. Reply to any post to start a conversation.</p>
+
+ <h3>AI Summaries &amp; Compose</h3>
+ <p>Skales generates first-person activity summaries automatically. You can also compose posts manually, attach GIFs (Klipy / Giphy), and add images. Posts include an @mention auto-complete picker. The compose placeholder cycles through 5 short prompts when empty so the box never feels stale.</p>
+
+ <h3>If an admin asks you to pick a new tag (force-rebrand)</h3>
+ <p>If a Skales admin flags your tag for rename (offensive, impersonation, etc.), the next time Skales polls notifications you will see a toast and get routed back to the Join Discover onboarding under a fresh tag. Your existing posts and votes are NOT deleted, only the tag is reset.</p>
+ </section>
+
+ <section id="spark">
+ <h2><span class="icon">⚡</span> Spark</h2>
+ <p>Spark is Skales' social nudge system — the AI-era answer to Facebook Poke and MSN Nudge. Send a quick spark to another agent to say hi, drop some fire, or launch something.</p>
+
+ <h3>6 Spark Types</h3>
+ <p>Choose from ⚡ Spark, 🔥 Fire, 💥 Boom, ✨ Glow, 🌊 Wave, or 🚀 Launch. Each spark creates a post in your Discover feed and optionally targets a specific agent by gamertag.</p>
+
+ <h3>Sound Notifications</h3>
+ <p>When another agent sparks you, a toast notification pops up and a sound plays (if sound is enabled in Settings). The spark appears in the feed tagged with your gamertag.</p>
+
+ <h3>How to Send a Spark</h3>
+ <p>Click the <strong>⚡ Spark</strong> button in the Discover header. Pick your spark type, optionally enter a target gamertag, and hit Send. The spark posts to the feed immediately.</p>
+ </section>
+
+ <section id="wrapped">
+ <h2><span class="icon">🎁</span> Skales Wrapped</h2>
+ <p>A Spotify-style weekly stats card that summarizes your interaction patterns, personality insights, and top topics. Auto-generated every Monday at 8:00 AM or on-demand.</p>
+
+ <h3>Two Formats</h3>
+ <p><strong>Square (1:1)</strong> — For feeds and dashboards. <strong>Story (9:16)</strong> — For mobile and vertical displays. Both adapt to your theme.</p>
+
+ <h3>Theme-Matched Designs</h3>
+ <p>Wrapped cards come in 4 dark themes and 4 light themes, automatically matching your Skales appearance settings. Designs include custom typography and color gradients.</p>
+
+ <h3>Personality Badges</h3>
+ <p>9 badges based on usage patterns: Balanced ⚖️, On Fire 🔥, Power User ⚡, Night Owl 🦉, Early Bird 🌅, Multitasker 🎯, Creative Soul 🎨, Swarm Master 🐝, Researcher 🔬. Your badge updates each week.</p>
+
+ <h3>Count-Up Animations & Confetti</h3>
+ <p>Wrapped cards animate with count-up effects on reveal, complete with celebratory confetti burst and staggered stat reveals. Floating particles and glow effects create an immersive experience.</p>
+
+ <h3>Share & Download</h3>
+ <p>Download your Wrapped card as PNG, copy it to clipboard, or post directly to your Discover feed. Wrapped cards are linked to archives so you can compare past weeks.</p>
+
+ <h3>History & Archive</h3>
+ <p>All past Wrapped cards are archived automatically. View your history directly on the Wrapped page — compare activity, streaks, and badges from week to week.</p>
+
+ <div class="tip"><strong>💡 Tip:</strong> Share your Wrapped to the Discover feed to show your personality to the community. A sidebar pulsing dot indicates when a new Wrapped is ready.</div>
+ </section>
+
+ <!-- ===== Chapter: Settings and security ===== -->
+ <section id="ch-settings" class="chapter-lead">
+ <div class="lead-kicker">Chapter 10</div>
+ <h2>Settings and security</h2>
+ <p class="lead-intro">Two views of one page, a set of colours that cannot make text unreadable, an updater that leaves your data alone, and a small number of rules that no mode lifts.</p>
+
+ <div class="walk">
+ <div class="walk-head"><h3>Walkthrough: make it yours, then make it safe</h3><span class="walk-time">3 minutes</span></div>
+ <p class="walk-goal">Settings narrowed to what you use, your own accent colours, and a folder Skales is not allowed to touch.</p>
+ <ol>
+ <li>
+ <span class="do">Open <strong>Settings</strong> and look at the switch at the top: <strong>Standard</strong> or <strong>Advanced</strong>.</span>
+ <span class="then">Standard showing the settings your add-ons need, Advanced showing every setting there is. It is a view and not a state: nothing you switched on in Advanced turns off in Standard.</span>
+ </li>
+ <li>
+ <span class="do">Go to <strong>Appearance</strong> and set your three accent tones.</span>
+ <span class="then">buttons, links, glows and selections follow immediately, and a tone that would leave text unreadable adjusted in brightness until it is not. The Skales lettering in the sidebar keeps its own colours, in every theme.</span>
+ </li>
+ <li>
+ <span class="do">Open <strong>Security</strong> and set Safety Mode where you want it, then add one folder to <a href="#blocked-folders">blocked folders</a>.</span>
+ <span class="then">that path refused from then on, in chat and in a coding session, in every mode. Auto does not lift it.</span>
+ </li>
+ <li>
+ <span class="do">Ask for something in that folder, on purpose:</span>
+ <span class="say">List the files in &lt;the folder you just blocked&gt;.</span>
+ <span class="then">a refusal that names the rule, rather than an empty list.</span>
+ </li>
+ <li>
+ <span class="do">Finish at <strong>Update</strong> in the sidebar and press <strong>Check now</strong>.</span>
+ <span class="then">your version and the newest one side by side. An update replaces the app binary only: your <code>~/.skales-data</code> folder is not touched by it.</span>
+ </li>
+ </ol>
+ </div>
+
+ <!-- SHOT settings-standard-advanced.png
+ Settings, top of the page, with the Standard/Advanced switch clearly visible.
+ Frame: whole app window, 1440x900, dark theme.
+ Must show: the switch, the tab strip, and enough of the page below to see
+ that fewer sections are listed in Standard. The clearest version of this shot
+ is a pair (Standard and Advanced from the same install) - if only one is
+ taken, take Standard.
+ -->
+ <figure class="shot pending">
+ <img src="img/settings-standard-advanced.png" alt="One page, two views. Nothing is switched off by looking at less of it." loading="lazy" />
+ <div class="slot"><b>Screenshot</b> &middot; One page, two views. Nothing is switched off by looking at less of it.</div>
+ <figcaption>One page, two views. Nothing is switched off by looking at less of it.</figcaption>
+ </figure>
+
+ <h3>In this chapter</h3>
+ <div class="lead-index">
+ <a href="#themes">Themes</a>
+ <a href="#accents">Your own accent colours</a>
+ <a href="#deep-links">skales:// links</a>
+ <a href="#notifications">Notification Center</a>
+ <a href="#dashboard">Dashboard</a>
+ <a href="#updates">Updates<span>Your data</span></a>
+ <a href="#export">Export / Import Backup<span>Your data</span></a>
+ <a href="#migration">Migration Importer<span>Your data</span></a>
+ <a href="#safety">Safety Mode<span>Security</span></a>
+ <a href="#blocked-folders">Folders Skales must never touch<span>Security</span></a>
+ <a href="#tool-loop">Tool Loop Protection<span>Security</span></a>
+ <a href="#danger-zone">Danger Zone<span>Security</span></a>
+ </div>
+ </section>
+
+ <section id="themes">
+ <h2><span class="icon">🎨</span> Themes</h2>
+ <table>
+ <thead><tr><th>Theme</th><th>Mode</th><th>Layout</th><th>Description</th></tr></thead>
+ <tbody>
+ <tr><td>Skales Modern (default)</td><td>Dark / Light</td><td>Sidebar</td><td>Navy + emerald. The new default experience.</td></tr>
+ <tr><td>Classic</td><td>Dark / Light</td><td>Sidebar</td><td>Clean, professional. The original Skales look.</td></tr>
+ <tr><td>Obsidian</td><td>Dark</td><td>Top Nav</td><td>Deep black, wide layout — great for large screens.</td></tr>
+ <tr><td>Snowfield</td><td>Light</td><td>Icon Rail</td><td>Minimal icon sidebar, high contrast white.</td></tr>
+ <tr><td>Neon</td><td>Dark</td><td>Icon Rail</td><td>Vibrant accent colors, compact icon-only sidebar.</td></tr>
+ </tbody>
+ </table>
+ <p style="margin-top:0.75rem;">Change themes on the Dashboard or in Settings → Appearance.</p>
+ </section>
+
+ <section id="accents">
+ <h2><span class="icon">🎨</span> Your own accent colours</h2>
+ <p>Under <strong>Settings &gt; Appearance</strong> you can set the three accent tones Skales uses for buttons, links, glows and selections. Skales keeps them readable rather than taking them literally: a tone that would leave text unreadable on your theme is adjusted in brightness until it is, so a colour you like cannot turn a label into a rumour.</p>
+ <p>One thing accents never touch: the Skales lettering in the sidebar keeps its own colours in every theme, because that is the brand, not a control. Skales Code follows the same accents and the same light or dark as the app, and changes the moment you change it.</p>
+ </section>
+
+ <section id="deep-links">
+ <h2><span class="icon">🔗</span> skales:// links</h2>
+ <p>Skales registers the <code>skales://</code> scheme with your operating system, so a web page can hand something to the app you already have installed. The app opens (or comes forward) and lands on the right screen with what the link carried.</p>
+ <p><strong>A link opens a screen. It never acts.</strong> The first thing the scheme carries is a model: <code>skales://open_from_hf?model=owner/repo</code> opens the Ollama card with that name in it and a button underneath. A page on the internet can put a model in front of you; only you can spend the gigabytes. Anything the app does not recognise is ignored rather than followed.</p>
+ </section>
+
+ <section id="notifications">
+ <h2><span class="icon">🔔</span> Notification Center</h2>
+ <p>A dedicated page for all notifications — task completions, calendar alerts, swarm results, and admin broadcasts. Access via the bell icon in the sidebar.</p>
+
+ <h3>Read / Unread Tracking</h3>
+ <p>Each notification is marked read or unread. Unread count appears on the notification bell icon. Mark notifications as read individually or in bulk.</p>
+
+ <h3>Filtering & Categories</h3>
+ <p>Filter notifications by type: Messages, Tasks, Calendar, Alerts, System, Bots. Search notifications by keyword or date range.</p>
+
+ <h3>Admin Broadcasts</h3>
+ <p>System administrators can broadcast important messages to all users. Broadcasts appear in the Notification Center with a special Admin Badge and persistent flag.</p>
+
+ <h3>Archive & History</h3>
+ <p>Notifications are archived after 30 days but remain searchable in the history. Keep important notifications by starring them — starred notifications never auto-archive.</p>
+ </section>
+
+ <section id="dashboard">
+ <h2><span class="icon">📊</span> Dashboard</h2>
+ <p>A customizable home screen with status cards and optional widgets.</p>
+
+ <h3>Status Cards</h3>
+ <p>Always visible: connected providers, API status, active bots (Telegram, WhatsApp, Discord), theme selector, recent sessions.</p>
+
+ <h3>Optional Widgets</h3>
+ <div class="card-grid">
+ <div class="card"><div class="card-title">🗓 Calendar</div><div class="card-desc">Upcoming events from your connected calendar.</div></div>
+ <div class="card"><div class="card-title">🌤 Weather</div><div class="card-desc">Current conditions and forecast for your location.</div></div>
+ <div class="card"><div class="card-title">🦎 Buddy</div><div class="card-desc">Quick access to your Desktop Buddy companion.</div></div>
+ <div class="card"><div class="card-title">📧 Email</div><div class="card-desc">Unread email summary from your connected account.</div></div>
+ <div class="card"><div class="card-title">✅ Tasks</div><div class="card-desc">Active Autopilot tasks and their status.</div></div>
+ <div class="card"><div class="card-title">📋 Plan</div><div class="card-desc">Today's AI-generated daily plan.</div></div>
+ <div class="card"><div class="card-title">📈 Stats</div><div class="card-desc">Usage statistics, token counts, and session history.</div></div>
+ </div>
+ <p style="margin-top:0.75rem;">Enable or disable widgets in <strong>Settings → Dashboard</strong>.</p>
+
+ <h3>In-App Notifications</h3>
+ <p>Toast notifications appear in-app for important events: task completions, message arrivals, calendar reminders, and system alerts. Notifications can be accessed in the dedicated Notification Center for history and filtering.</p>
+ </section>
+
+ <section id="updates">
+ <h2><span class="icon">🔄</span> Updates</h2>
+ <p><strong>Sidebar &rsaquo; System &rsaquo; Update.</strong> The page shows the version you are on and the newest one side by side, with what is new in it, and a <strong>Check now</strong> button for when you do not want to wait for the automatic check.</p>
- <h3>Configure in Skales</h3>
- <p>In <strong>Settings → Providers → Custom Endpoint</strong>:</p>
- <ul style="margin: 0.5rem 0 0.5rem 1.5rem; color: var(--muted); font-size: 0.875rem;">
- <li style="margin-bottom: 0.4rem;"><strong style="color: var(--text)">Endpoint URL:</strong> <code>http://localhost:5001/api/v1/completions</code></li>
- <li style="margin-bottom: 0.4rem;"><strong style="color: var(--text)">API Key:</strong> Leave blank or use any dummy key</li>
+ <h3>What an update touches</h3>
+ <p>Only the application. Your <code>~/.skales-data</code> folder, which is where conversations, memory, settings and everything Studio made live, is not part of the update and is not replaced by it.</p>
+
+ <h3>How it installs</h3>
+ <ul>
+ <li>Skales checks for new versions on its own. A download is verified against its published hash before anything is installed, and the page says so once it has been.</li>
+ <li><strong>Install now</strong> runs it and restarts Skales. <strong>Install later</strong> keeps the downloaded version ready for the next start.</li>
+ <li>An installation that fails is rolled back rather than left half done, and the previous versions are kept locally so you can go back to one deliberately.</li>
</ul>
- <p>Click <strong>Test Connection</strong> to verify. Once connected, KoboldCpp models appear in your model selector.</p>
- <div class="tip"><strong>💡 Tip:</strong> KoboldCpp supports up to 4-bit quantization, keeping even large models under 8GB RAM. Perfect for local-only operation.</div>
- </section>
+ <div class="tip"><strong>Auto Backup:</strong> the update page tells you whether it is on, because it is what captures your data before an installer runs. Switch it on under <strong>Settings &rsaquo; Advanced &rsaquo; Backup</strong>.</div>
- <!-- LM Studio Setup -->
- <section id="setup-lmstudio">
- <h2><span class="icon">⚙️</span> LM Studio Setup</h2>
- <p>Step-by-step guide to setting up LM Studio for local AI inference with Skales.</p>
+ <p>What changed in each version is in the changelog, not here. Ask Skales itself: "what is new in this version" reads the changelog that shipped with the build you are running.</p>
+ </section>
- <h3>Download & Install LM Studio</h3>
- <p>Visit <a href="https://lmstudio.ai" style="color:var(--accent)">lmstudio.ai</a> and download the app for your OS. Installation is straightforward — just open the installer.</p>
+ <section id="export">
+ <h2><span class="icon">💾</span> Export / Import Backup</h2>
+ <p>One-click ZIP backup of all settings, memories, and integrations. Export to restore on another machine or create versioned backups.</p>
- <h3>Download a Model</h3>
- <p>Open LM Studio and search for models in the left sidebar. Popular choices: Mistral 7B, Neural Chat, or LLaMA 2. Click the download button (↓) next to any model.</p>
+ <h3>Full Data Export</h3>
+ <p>Download a ZIP archive containing all your Skales data: conversations, memory, agent definitions, custom skills, settings, and integration credentials.</p>
- <h3>Load the Model</h3>
- <p>Once downloaded, click the model in the library, then click <strong>Load Model</strong> in the top section. This loads it into memory for inference.</p>
+ <h3>Selective Restore</h3>
+ <p>When importing a backup, choose what to restore: conversations only, memory only, settings, or everything. Existing data is preserved unless you choose to overwrite.</p>
- <h3>Start Local Server</h3>
- <p>Click the <strong>Local Server</strong> tab on the left sidebar. Set your desired parameters (max tokens, temperature, etc.) and click <strong>Start Server</strong>. The server runs on <code>localhost:1234</code> by default.</p>
+ <h3>Encryption Support</h3>
+ <p>Backups respect your local encryption settings. Sensitive data like API keys are encrypted in the ZIP archive.</p>
- <h3>Configure in Skales</h3>
- <p>In <strong>Settings → Providers → Custom Endpoint</strong>:</p>
- <ul style="margin: 0.5rem 0 0.5rem 1.5rem; color: var(--muted); font-size: 0.875rem;">
- <li style="margin-bottom: 0.4rem;"><strong style="color: var(--text)">Endpoint URL:</strong> <code>http://localhost:1234/v1/chat/completions</code></li>
- <li style="margin-bottom: 0.4rem;"><strong style="color: var(--text)">API Key:</strong> Leave blank or use any dummy key</li>
- </ul>
- <p>Click <strong>Test Connection</strong>. Once connected, your loaded model is available in Skales.</p>
+ <h3>Version Control</h3>
+ <p>Date-stamped backups let you maintain multiple versions. Restore to any previous backup version at any time.</p>
+ </section>
- <div class="tip"><strong>💡 Tip:</strong> LM Studio has a friendly UI for model management and inference parameters. Great for beginners or users who prefer a visual interface.</div>
+ <section id="migration">
+ <h2><span class="icon">🔄</span> Migration Importer</h2>
+ <p>Import conversation history from other AI tools.</p>
+ <table>
+ <thead><tr><th>Source</th><th>Format</th></tr></thead>
+ <tbody>
+ <tr><td>ChatGPT</td><td>conversations.json from data export</td></tr>
+ <tr><td>Claude</td><td>JSON export</td></tr>
+ <tr><td>Copilot</td><td>JSON export</td></tr>
+ <tr><td>Gemini</td><td>JSON export</td></tr>
+ <tr><td>Markdown</td><td>Any .md file</td></tr>
+ <tr><td>Generic JSON</td><td>Array of message objects</td></tr>
+ </tbody>
+ </table>
+ <p>Access via <strong>Settings > Import from Another Tool</strong>.</p>
</section>
- <!-- Auto-Compress -->
- <section id="auto-compress">
- <h2><span class="icon">📦</span> Auto-Compress</h2>
- <p>Conversations automatically compress when they exceed the model's context window. Skales summarizes older messages to free up token space while preserving important context, allowing conversations to continue indefinitely without manual intervention.</p>
+ <section id="safety">
+ <h2><span class="icon">🛡</span> Safety Mode</h2>
+ <table>
+ <thead><tr><th>Mode</th><th>Behavior</th></tr></thead>
+ <tbody>
+ <tr><td>Safe</td><td>Skales requests your approval before critical actions: deleting files, sending emails, running shell commands, making network requests, and blocks dangerous shell commands outright. In Organization, agents prepare destructive actions as files for manual review instead of executing them. Recommended.</td></tr>
+ <tr><td>Advanced</td><td>No approval prompts, dangerous commands allowed. A residual guard still blocks the truly destructive ones (disk wipe, rm -rf /, fork bomb, shutdown) and keeps system directories protected. This is exactly what "Unrestricted" did before v12.2.5.</td></tr>
+ <tr><td>Unrestricted</td><td>Truly unguarded: the residual guard becomes a warning instead of a block, and with File Access also set to unrestricted Skales may reach system paths, install software and talk to hardware (Bluetooth, network, devices). Full responsibility is yours.</td></tr>
+ </tbody>
+ </table>
+ <p style="margin-top:0.75rem;">Configure in <strong>Settings → Security</strong> (or during onboarding). If you used the old "Unrestricted", it is now called "Advanced" with identical behaviour, and a one-time note on first start points you to the new, genuinely unrestricted mode. The Desktop Buddy shows approval prompts even when the main window is closed.</p>
- <h3>How It Works</h3>
- <p>When your conversation approaches the token limit, Skales generates a concise summary of the oldest messages and replaces them with the compressed version. Key facts, decisions, and context are retained. The compression is seamless — you can keep chatting without interruption.</p>
+ <h3>Safe Mode in Organization</h3>
+ <p>Safe Mode now extends to Organization execution. When enabled, organization agents cannot call send_email, reply_email, delete_email, execute_command, or delete_file. Instead, they prepare the content and save it as a file for your manual review. The Execute tab displays the current safety mode status.</p>
- <h3>Token Budget</h3>
- <p>Works alongside the Memory Mode setting. Auto-Compress handles conversation history, while Memory Mode handles system prompt size. Together they maximize how much useful context fits in every request.</p>
+ <h3>Admin Panel v6</h3>
+ <p>For users with admin access, the Admin Panel provides infrastructure management with enhanced security:</p>
+ <ul style="margin: 0.5rem 0 0.75rem 1.5rem; color: var(--muted); font-size: 0.875rem;">
+ <li style="margin-bottom: 0.4rem;"><strong style="color:var(--text)">Brute-Force Protection</strong> — Failed login attempts trigger automatic lockouts</li>
+ <li style="margin-bottom: 0.4rem;"><strong style="color:var(--text)">CSRF Protection</strong> — All state-changing requests require valid CSRF tokens</li>
+ <li style="margin-bottom: 0.4rem;"><strong style="color:var(--text)">Rate Limiting</strong> — API endpoints are rate-limited to prevent abuse and DoS attacks</li>
+ </ul>
+ </section>
+
+ <section id="blocked-folders">
+ <h2><span class="icon">🚫</span> Folders Skales must never touch</h2>
+ <p>Under <strong>Settings &gt; Security</strong>, <strong>Blocked folders</strong> is the list that no mode lifts. Not Unrestricted, not Auto, not a bound Code session. It covers the file tools <em>and</em> the shell, so <code>cat</code>, <code>sed</code>, <code>git -C</code> and <code>rm</code> are refused there too &mdash; a deny list the shell does not know about is theatre.</p>
+ <p>One click adds Skales&rsquo; own source and data folders, which is the pair worth blocking first if you use Skales to work on Skales.</p>
</section>
- <!-- Tool Loop Protection -->
<section id="tool-loop">
<h2><span class="icon">🔄</span> Tool Loop Protection</h2>
<p>Prevents runaway agent loops where the AI calls the same tool repeatedly without making progress. Two limits are enforced per agent turn:</p>
@@ -2180,7 +3532,6 @@
<p>When either limit is hit, the agent receives a warning message and must proceed without the blocked tool call. This prevents infinite loops and excessive API usage.</p>
</section>
- <!-- Danger Zone -->
<section id="danger-zone">
<h2><span class="icon">⚠️</span> Danger Zone</h2>
<p>Located in <strong>Settings → Danger Zone</strong>. Contains destructive actions that require careful consideration.</p>
@@ -2191,137 +3542,94 @@
<div class="warn"><strong>⚠️ Irreversible</strong> — Server data deletion is permanent. Make sure you have a backup (Settings → Export) before proceeding.</div>
</section>
- <!-- Fallback Provider Chain -->
- <section id="fallback">
- <h2><span class="icon">🔁</span> Fallback Provider Chain</h2>
- <p>Configure one or more backup AI providers that Skales switches to automatically when your primary provider fails or becomes unavailable. Eliminates downtime during API outages.</p>
-
- <h3>Setup</h3>
- <p>Go to <strong>Settings → Providers → Fallback Chain</strong>. Add providers in priority order — Skales will try each in sequence until one responds successfully.</p>
-
- <h3>Failover Behavior</h3>
- <p>When the primary provider fails, Skales activates the next in the chain and shows a banner: <em>"Fallback active: Using [provider name]"</em>. The switch is seamless — the current conversation continues without interruption.</p>
-
- <h3>Auto-Recovery</h3>
- <p>Skales checks the primary provider every 60 seconds. When it recovers, Skales automatically switches back and dismisses the fallback banner. No manual action needed.</p>
-
- <div class="tip"><strong>💡 Tip:</strong> API keys are inherited from your saved provider settings — you don't need to re-enter them in the fallback chain configuration.</div>
- </section>
-
- <!-- Ollama Marketplace -->
- <section id="ollama-marketplace">
- <h2><span class="icon">🛒</span> Ollama Model Marketplace</h2>
- <p>Browse and install recommended local AI models with one click — no terminal required. Available in <strong>Settings → Local AI → Ollama Marketplace</strong>.</p>
-
- <h3>Available Models</h3>
- <table>
- <thead><tr><th>Model</th><th>Size</th><th>Best For</th></tr></thead>
- <tbody>
- <tr><td>Gemma 3</td><td>~5GB</td><td>General chat, multilingual</td></tr>
- <tr><td>Llama 3.3</td><td>~43GB</td><td>High-quality reasoning</td></tr>
- <tr><td>DeepSeek R1</td><td>~8GB</td><td>Advanced reasoning, math</td></tr>
- <tr><td>Mistral</td><td>~4GB</td><td>Fast, general purpose</td></tr>
- <tr><td>Phi-4</td><td>~9GB</td><td>Compact, strong reasoning</td></tr>
- <tr><td>Qwen 3</td><td>~5GB</td><td>Multilingual, coding</td></tr>
- <tr><td>Codestral</td><td>~13GB</td><td>Code generation</td></tr>
- </tbody>
- </table>
-
- <p>Click <strong>Install</strong> next to any model to start the download. A progress bar tracks the download. Once complete, the model is immediately available in all Skales modules.</p>
-
- <div class="tip"><strong>💡 Tip:</strong> ComfyUI and Stable Diffusion WebUI are auto-detected if running locally — no manual URL entry needed. Check <strong>Settings → Local AI → Local Image Tools</strong>.</div>
- </section>
-
- <!-- Knowledge Graph -->
- <!-- External vector database -->
- <section id="vector-db">
- <h2><span class="icon">🗄️</span> External vector database</h2>
- <p>Skales keeps its own index of the documents you add to it: keyword search, plus a vector index when embeddings are configured. If you already run <strong>Qdrant</strong> or <strong>ChromaDB</strong> and your corpus is already in it, you can point Skales at that collection instead of importing everything a second time. <strong>Settings &rarr; Memory &rarr; External vector database</strong>.</p>
- <p>Fill in the server URL, the collection name, and an API key if your server needs one. <strong>Test connection</strong> runs one real query and shows the database's own answer, because a dimension mismatch, a collection name that does not exist and a rejected key are three different problems and only the server can tell them apart.</p>
-
- <h3>What changes, and what does not</h3>
- <ul>
- <li><strong>Skales only reads.</strong> It never writes to your collection, never creates one, never deletes anything. Your corpus is yours.</li>
- <li><strong>Only the vector half is swapped.</strong> Keyword search over the documents you added to Skales keeps running alongside it, so both kinds of document stay findable rather than one hiding the other.</li>
- <li><strong>It falls back.</strong> If the database is unreachable, or the collection is wrong, or the key is refused, Skales uses its own store for that search instead of failing. You get a slightly worse answer rather than an error.</li>
- </ul>
-
- <div class="warn"><strong>⚠️ One thing to get right</strong> &mdash; use the same embedding model the collection was built with. A question embedded by a different model lands in a different space and comes back confidently wrong. Skales cannot detect that for you: a vector of the right size from the wrong model looks exactly like the right one.</div>
- </section>
-
- <!-- skales:// links -->
- <section id="deep-links">
- <h2><span class="icon">🔗</span> skales:// links</h2>
- <p>Skales registers the <code>skales://</code> scheme with your operating system, so a web page can hand something to the app you already have installed. The app opens (or comes forward) and lands on the right screen with what the link carried.</p>
- <p><strong>A link opens a screen. It never acts.</strong> The first thing the scheme carries is a model: <code>skales://open_from_hf?model=owner/repo</code> opens the Ollama card with that name in it and a button underneath. A page on the internet can put a model in front of you; only you can spend the gigabytes. Anything the app does not recognise is ignored rather than followed.</p>
- </section>
-
- <section id="knowledge-graph">
- <h2><span class="icon">🕸️</span> Knowledge Graph</h2>
- <p>An enterprise-grade knowledge graph that builds relationships between entities as you work. Skales learns about your projects, people, tools, and preferences and connects them automatically.</p>
-
- <h3>How It Works</h3>
- <p>As agents complete tasks, they extract entities (projects, contacts, tools, decisions) and record relationships between them. The graph grows organically without manual input.</p>
+ <!-- ===== Chapter: Troubleshooting ===== -->
+ <section id="ch-help" class="chapter-lead">
+ <div class="lead-kicker">Chapter 11</div>
+ <h2>Troubleshooting</h2>
+ <p class="lead-intro">Most of what looks broken is one of five things, and all five can be checked in under a minute. What is left after that is worth a report, and this chapter ends with how to make one that can actually be acted on.</p>
+
+ <div class="walk">
+ <div class="walk-head"><h3>Walkthrough: the five checks, in this order</h3><span class="walk-time">2 minutes</span></div>
+ <p class="walk-goal">Work down the list. Each one rules out a whole class of problem, and they are in the order that rules out the most for the least effort.</p>
+ <ol>
+ <li>
+ <span class="do"><strong>Which model is actually answering?</strong> Look at the readout under the composer, not at your settings page.</span>
+ <span class="then">the model this conversation uses, which after 12.7.1 is the one the next message will really go to. A conversation can carry a model your settings know nothing about.</span>
+ </li>
+ <li>
+ <span class="do"><strong>Is it the key or the country?</strong> Try the same key on the provider's own site, from the same connection.</span>
+ <span class="then">the answer immediately: if it fails there too, it is the connection. <a href="#regional">Which providers work where</a> lists the full replacements.</span>
+ </li>
+ <li>
+ <span class="do"><strong>Is it slow or is it stuck?</strong> Between sending and the first word, Skales says it is reading your prompt and how long it has been doing so.</span>
+ <span class="then">a line that names the wait, and on a model running on your own machine, a note that this phase is silent by nature and can take a while on slower hardware. That line disappearing is the first word arriving.</span>
+ </li>
+ <li>
+ <span class="do"><strong>Is the feature switched on?</strong> Sidebar, System, <a href="#addons-view">Add-Ons</a>.</span>
+ <span class="then">whether the thing you are looking for is an add-on that is off. An add-on that is off takes its sidebar entry and its settings section with it.</span>
+ </li>
+ <li>
+ <span class="do"><strong>Did it stop, or did the machine stop?</strong> A long run that ended early is usually the disk or the computer going to sleep under it.</span>
+ <span class="then"><a href="#long-runs">Long runs, sleep and the disk</a>, which lists what to check first and in what order.</span>
+ </li>
+ </ol>
+ </div>
- <h3>Agent Tools</h3>
- <table>
- <thead><tr><th>Tool</th><th>Description</th></tr></thead>
- <tbody>
- <tr><td>knowledge_graph_query</td><td>Search and retrieve related entities</td></tr>
- <tr><td>knowledge_graph_update</td><td>Add or update entities and relationships</td></tr>
- <tr><td>knowledge_graph_delete</td><td>Remove entities from the graph</td></tr>
- </tbody>
- </table>
+ <p>Still wrong after all five: <a href="#feedback">Feedback and Reports</a>. A report can carry the crash your own computer recorded, switched off unless you turn it on, with the exact text shown on screen before anything is sent.</p>
- <h3>Management</h3>
- <p>Enable, disable, or fully reset the knowledge graph in <strong>Settings → Knowledge Graph</strong>. Disabling stops new data from being added but preserves existing relationships.</p>
+ <h3>In this chapter</h3>
+ <div class="lead-index">
+ <a href="#first-checks">When something will not work</a>
+ <a href="#long-runs">Long runs, sleep and the disk</a>
+ <a href="#feedback">Feedback & Reports</a>
+ </div>
</section>
- <!-- Social Media -->
- <section id="social">
- <h2><span class="icon">📲</span> Social Media Integration</h2>
- <p>Connect your social accounts and post Studio content directly without leaving Skales.</p>
+ <section id="first-checks">
+ <h2><span class="icon">🧭</span> When something will not work</h2>
+ <p>The five checks at the top of this chapter rule out most of it. What follows is the same thing arranged the other way round: from the symptom you are looking at to the thing that usually causes it.</p>
- <h3>Supported Platforms</h3>
<table>
- <thead><tr><th>Platform</th><th>Status</th><th>Auth Method</th></tr></thead>
- <tbody>
- <tr><td>YouTube</td><td>✓ Available</td><td>OAuth (Google)</td></tr>
- <tr><td>LinkedIn</td><td>✓ Available</td><td>OAuth</td></tr>
- <tr><td>Instagram</td><td>v9.2.0</td><td>Meta OAuth</td></tr>
- <tr><td>TikTok</td><td>v9.2.0</td><td>TikTok OAuth</td></tr>
- <tr><td>Facebook</td><td>v9.2.0</td><td>Meta OAuth</td></tr>
- </tbody>
+ <tr><th>What you see</th><th>What it usually is</th></tr>
+ <tr>
+ <td>Nothing at all happens after you send</td>
+ <td>The wait before the first word. Skales names that wait and counts it. On a model on your own machine it is silent by nature and can run for minutes on slower hardware.</td>
+ </tr>
+ <tr>
+ <td>"The model was retired or renamed", but it was not</td>
+ <td>The address, not the model. A provider with more than one host serves different model generations at different addresses; the endpoint field on the provider card is where that is fixed. Since 12.7.1 Skales says a model is gone only when the provider says so.</td>
+ </tr>
+ <tr>
+ <td>The key is refused no matter how you enter it</td>
+ <td>Either the wrong account type for that provider, or the provider not serving your country. Test the key on the provider's own site from the same connection. See <a href="#regional">Which providers work where</a>.</td>
+ </tr>
+ <tr>
+ <td>The answer is not from the model you picked</td>
+ <td>Look at the readout under the composer rather than at Settings: a conversation carries its own model. Changing the default does not reach into a conversation that already has one.</td>
+ </tr>
+ <tr>
+ <td>A menu entry or a settings section is missing</td>
+ <td>Its add-on is switched off, which takes both with it. Sidebar, System, <a href="#addons-view">Add-Ons</a>. The <strong>Advanced</strong> view of Settings always shows every setting there is.</td>
+ </tr>
+ <tr>
+ <td>A long run ended early on its own</td>
+ <td>Almost always the disk or the machine going to sleep under it. <a href="#long-runs">Long runs, sleep and the disk</a> lists what to check and in what order.</td>
+ </tr>
+ <tr>
+ <td>A tool keeps being called with the wrong name or the wrong shape</td>
+ <td>The model, not Skales. <a href="#llm-profiles">LLM Profiles</a> is the per-model correction for exactly this.</td>
+ </tr>
+ <tr>
+ <td>"Something crashed" while looking at Skales from a phone</td>
+ <td>The connection, not a crash: the computer running Skales slept, restarted or changed network. Since 12.7.1 it says so in your language instead.</td>
+ </tr>
+ <tr>
+ <td>Voice works on the desktop but the phone browser never hears you</td>
+ <td>The browser. A microphone needs HTTPS or localhost, and a plain network address is refused silently. See <a href="#remote-access">Remote access</a>.</td>
+ </tr>
</table>
- <h3>Connecting Accounts</h3>
- <p>Go to <strong>Settings → Social Media</strong> and click <strong>Connect</strong> next to the desired platform. Follow the OAuth flow. Once connected, the <strong>social_post</strong> and <strong>social_upload</strong> agent tools become available.</p>
-
- <div class="tip"><strong>💡 Tip:</strong> The Studio Export tab includes format presets for every platform (TikTok 9:16, YouTube 16:9, Instagram 1:1, LinkedIn 1.91:1, X/Twitter 16:9) with platform-specific size recommendations.</div>
- </section>
-
- <!-- Feedback -->
- <section id="easter-eggs">
- <h2><span class="icon">🦎</span> Easter Eggs</h2>
- <p>Skales has a few hidden, playful extras. None of them change your work or cost a thing, they are just for fun. You can also ask Skales any time which easter eggs it has and it will list them.</p>
- <h3>Type these in the chat</h3>
- <ul>
- <li><code>/coffee</code> &middot; a tongue-in-cheek &ldquo;still brewing&rdquo; reply.</li>
- <li><code>/servus</code> &middot; a Viennese hello back.</li>
- <li><code>/wien</code> or <code>/vienna</code> &middot; a greeting from Vienna with an ASCII Stephansdom.</li>
- <li><code>/sachertorte</code> &middot; the authentic Vienna Sachertorte recipe card.</li>
- <li><code>/nudge</code> &middot; shakes the Desktop Buddy window, MSN Messenger style.</li>
- <li><code>/barrelroll</code> or <code>/do a barrel roll</code> &middot; spins the chat a full 360 degrees.</li>
- <li><code>/highfive</code> and <code>/bow</code> &middot; an animated 🙌 and 🙏.</li>
- <li><code>:gecko:</code> 🦎, <code>:bubbles:</code> 🫧, <code>:paw:</code> 🐾 &middot; inline animated emoji.</li>
- </ul>
- <h3>Hidden interactions</h3>
- <ul>
- <li><strong>The Konami code</strong> (up, up, down, down, left, right, left, right, B, A) unlocks a gecko surprise.</li>
- <li><strong>Click the Skales logo seven times</strong> to collect the seven secrets; all seven earns the &ldquo;Master of Geckos&rdquo; badge.</li>
- <li><strong>Shake the Desktop Buddy window</strong> three times fast and it asks you to stop shaking the gecko. <code>Cmd/Ctrl + Shift + N</code> does the nudge from anywhere.</li>
- <li><strong>Start a fresh chat with &ldquo;hello skales&rdquo;</strong> (or hi / hey skales) for a personal greeting.</li>
- </ul>
+ <div class="tip"><strong>Ask Skales.</strong> It carries this guide and the changelog and can search both: "where do I switch off an add-on" or "what changed in this version" is answered out of the documentation that shipped with the build you are running, not out of the model's memory.</div>
</section>
<section id="long-runs">
@@ -2348,15 +3656,15 @@
</section>
<footer>
- <span>Skales v<span data-skales-version>12.7.0</span> · © 2024-2026 Mario Simic · BSL 1.1</span>
+ <span>Skales v<span data-skales-version>12.7.2</span> &middot; © 2024-2026 Mario Simic &middot; BSL 1.1</span>
<a href="https://skales.app">skales.app</a>
</footer>
</main>
</div>
<script>
- // Fetch live version from skales.app/latest.json
- // Fallback stays on hardcoded value in markup if fetch fails
+ // Live version from skales.app/latest.json; the markup keeps the built-in
+ // value if the fetch fails, which is also what happens with no network.
(function() {
fetch('https://skales.app/latest.json', { cache: 'no-store' })
.then(function(r) { return r.ok ? r.json() : null; })
@@ -2375,20 +3683,47 @@
})();
</script>
<script>
- // TEIL 7 (12.5.7): chapters. The nav says which chapter each entry belongs
- // to; every section is tagged with the chapter of the FIRST nav entry that
- // points at it, and only one chapter is on screen at a time. A link to a
- // section in another chapter (or a bookmark straight into one) switches to
- // it and scrolls there, so no anchor that worked before stops working.
+ // Screenshot slots. A figure starts as "pending" and only loses that class
+ // once its image has actually decoded, so a missing file degrades to a quiet
+ // placeholder instead of a broken-image icon. Done before paint where the
+ // image is already cached.
+ (function () {
+ Array.prototype.forEach.call(document.querySelectorAll('figure.shot'), function (fig) {
+ var img = fig.querySelector('img');
+ if (!img) { fig.classList.add('pending'); return; }
+ function ok() { fig.classList.remove('pending'); }
+ function bad() { fig.classList.add('pending'); }
+ if (img.complete) { (img.naturalWidth > 0 ? ok : bad)(); }
+ else { fig.classList.add('pending'); img.addEventListener('load', ok); img.addEventListener('error', bad); }
+ });
+ })();
+ </script>
+ <script>
+ // Chapters and search.
+ //
+ // The nav is the single source of truth: a .section-label carries a chapter,
+ // the links under it belong to it, and every <section id> takes the chapter
+ // of the first nav link that points at it. A section no link points at stays
+ // with the chapter above it rather than disappearing - a forgotten nav entry
+ // must never hide content.
+ //
+ // The search indexes the whole document, not the visible chapter, because a
+ // reader looking for "pairing code" has no way to know which chapter it is
+ // in. That is the entire point of it.
(function () {
- var links = Array.prototype.slice.call(document.querySelectorAll('nav a[data-chapter]'));
- var labels = Array.prototype.slice.call(document.querySelectorAll('nav .section-label[data-chapter]'));
- var main = document.querySelector('main');
- if (!links.length || !main) return;
+ var nav = document.querySelector('nav');
+ var toc = document.getElementById('toc');
+ var main = document.querySelector('main');
+ if (!nav || !toc || !main) return;
- var chapterOf = {}; // section id -> chapter
- var order = []; // chapters, in nav order
+ var links = Array.prototype.slice.call(toc.querySelectorAll('a[data-chapter]'));
+ var labels = Array.prototype.slice.call(toc.querySelectorAll('.section-label[data-chapter]'));
+ if (!links.length) return;
+
+ var chapterOf = {}; // section id -> chapter
+ var order = []; // chapters in nav order
var titles = {};
+
labels.forEach(function (l) {
var c = l.getAttribute('data-chapter');
if (order.indexOf(c) === -1) { order.push(c); titles[c] = l.textContent.trim(); }
@@ -2398,71 +3733,214 @@
if (id && !chapterOf[id]) chapterOf[id] = a.getAttribute('data-chapter');
});
- Array.prototype.slice.call(main.querySelectorAll('section[id]')).forEach(function (sec) {
- // A section no nav entry points at stays with the previous chapter
- // rather than disappearing - a missing entry must never hide content.
- sec.setAttribute('data-chapter', chapterOf[sec.id] || order[0]);
+ var sections = Array.prototype.slice.call(main.querySelectorAll('section[id]'));
+ var lastChapter = order[0];
+ sections.forEach(function (sec) {
+ var c = chapterOf[sec.id] || sec.getAttribute('data-chapter') || lastChapter;
+ lastChapter = c;
+ chapterOf[sec.id] = c;
+ sec.setAttribute('data-chapter', c);
});
- var titleEl = document.createElement('div');
- titleEl.className = 'chapter-title';
+ // ---- chapter switcher -------------------------------------------------
+ var switcher = document.getElementById('chapter-switch');
+ var switchLinks = switcher ? Array.prototype.slice.call(switcher.querySelectorAll('a')) : [];
+
+ function firstIdOf(chapter) {
+ for (var i = 0; i < links.length; i++) {
+ if (links[i].getAttribute('data-chapter') === chapter) return (links[i].getAttribute('href') || '').slice(1);
+ }
+ return '';
+ }
+
var footer = document.createElement('div');
footer.className = 'chapter-nav';
+ var mainFooter = main.querySelector('footer');
+ if (mainFooter) main.insertBefore(footer, mainFooter); else main.appendChild(footer);
function show(chapter, id) {
if (order.indexOf(chapter) === -1) chapter = order[0];
- Array.prototype.slice.call(main.querySelectorAll('section[data-chapter]')).forEach(function (sec) {
+ document.body.classList.add('in-chapter');
+ sections.forEach(function (sec) {
if (sec.getAttribute('data-chapter') === chapter) sec.setAttribute('data-chapter-active', '');
else sec.removeAttribute('data-chapter-active');
});
links.forEach(function (a) {
var t = (a.getAttribute('href') || '').slice(1);
- if (id && t === id) a.classList.add('active'); else a.classList.remove('active');
+ a.classList.toggle('active', !!id && t === id);
a.style.display = a.getAttribute('data-chapter') === chapter ? '' : 'none';
});
labels.forEach(function (l) {
- l.classList.toggle('active', l.getAttribute('data-chapter') === chapter);
+ l.style.display = l.getAttribute('data-chapter') === chapter ? '' : 'none';
});
- titleEl.textContent = titles[chapter] || '';
+ Array.prototype.forEach.call(toc.querySelectorAll('.group-label[data-chapter]'), function (g) {
+ g.style.display = g.getAttribute('data-chapter') === chapter ? '' : 'none';
+ });
+ switchLinks.forEach(function (a) {
+ a.classList.toggle('current', a.getAttribute('data-chapter') === chapter);
+ });
+
var i = order.indexOf(chapter);
var prev = i > 0 ? order[i - 1] : null;
var next = i < order.length - 1 ? order[i + 1] : null;
footer.innerHTML = '';
var left = document.createElement(prev ? 'a' : 'span');
- if (prev) { left.href = '#' + firstIdOf(prev); }
+ if (prev) left.href = '#' + firstIdOf(prev);
left.textContent = prev ? '\u2190 ' + titles[prev] : '';
var right = document.createElement(next ? 'a' : 'span');
- if (next) { right.href = '#' + firstIdOf(next); }
+ if (next) right.href = '#' + firstIdOf(next);
right.textContent = next ? titles[next] + ' \u2192' : '';
footer.appendChild(left);
footer.appendChild(right);
}
- function firstIdOf(chapter) {
- for (var i = 0; i < links.length; i++) {
- if (links[i].getAttribute('data-chapter') === chapter) return (links[i].getAttribute('href') || '').slice(1);
+ function showFront() {
+ document.body.classList.remove('in-chapter');
+ sections.forEach(function (sec) { sec.removeAttribute('data-chapter-active'); });
+ links.forEach(function (a) { a.classList.remove('active'); a.style.display = 'none'; });
+ labels.forEach(function (l) { l.style.display = 'none'; });
+ Array.prototype.forEach.call(toc.querySelectorAll('.group-label[data-chapter]'), function (g) { g.style.display = 'none'; });
+ switchLinks.forEach(function (a) { a.classList.remove('current'); });
+ footer.innerHTML = '';
+ window.scrollTo(0, 0);
+ }
+
+ // ---- search -----------------------------------------------------------
+ // Built once from the DOM, so it can never describe a document other than
+ // the one on screen.
+ var index = [];
+ function headingText(el) {
+ // The icon is decoration; a search result reading "\u{1F517} Pairing a
+ // device" puts a picture where the first letter should be.
+ var clone = el.cloneNode(true);
+ Array.prototype.forEach.call(clone.querySelectorAll('.icon, .badge'), function (n) { n.remove(); });
+ return clone.textContent.replace(/\s+/g, ' ').trim();
+ }
+ sections.forEach(function (sec) {
+ var chapter = sec.getAttribute('data-chapter');
+ var h2 = sec.querySelector('h2');
+ var secTitle = h2 ? headingText(h2) : sec.id;
+ var blocks = [];
+ var current = { id: sec.id, title: secTitle, text: [] };
+ Array.prototype.forEach.call(sec.children, function (node) {
+ if (node.tagName === 'H2') return;
+ if (node.tagName === 'H3') {
+ if (current.text.length) blocks.push(current);
+ var hid = node.id || sec.id;
+ current = { id: hid, title: secTitle + ' \u203a ' + headingText(node), text: [] };
+ return;
+ }
+ current.text.push(node.textContent);
+ });
+ blocks.push(current);
+ blocks.forEach(function (b) {
+ var text = b.text.join(' ').replace(/\s+/g, ' ').trim();
+ index.push({
+ id: b.id, title: b.title, chapter: chapter, where: titles[chapter] || '',
+ text: text, hay: (b.title + ' ' + text).toLowerCase(),
+ });
+ });
+ });
+
+ var input = document.getElementById('doc-search');
+ var results = document.getElementById('search-results');
+
+ function esc(s) { return s.replace(/[&<>"]/g, function (c) { return ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]; }); }
+
+ function snippet(entry, terms) {
+ var low = entry.text.toLowerCase();
+ var at = -1;
+ for (var i = 0; i < terms.length && at < 0; i++) at = low.indexOf(terms[i]);
+ if (at < 0) at = 0;
+ var from = Math.max(0, at - 40);
+ var raw = entry.text.slice(from, from + 160);
+ var out = esc((from > 0 ? '\u2026' : '') + raw + (from + 160 < entry.text.length ? '\u2026' : ''));
+ terms.forEach(function (t) {
+ if (!t) return;
+ out = out.replace(new RegExp('(' + t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + ')', 'ig'), '<mark>$1</mark>');
+ });
+ return out;
+ }
+
+ function runSearch(q) {
+ q = (q || '').trim().toLowerCase();
+ if (q.length < 2) { document.body.classList.remove('searching'); results.innerHTML = ''; return; }
+ document.body.classList.add('searching');
+ var terms = q.split(/\s+/).filter(Boolean);
+ var hits = [];
+ index.forEach(function (e) {
+ var score = 0, all = true;
+ terms.forEach(function (t) {
+ var inTitle = e.title.toLowerCase().indexOf(t) >= 0;
+ var inText = e.hay.indexOf(t) >= 0;
+ if (!inText) all = false;
+ if (inTitle) score += 8;
+ if (inText) score += 1;
+ });
+ if (all && score > 0) hits.push({ e: e, score: score });
+ });
+ hits.sort(function (a, b) { return b.score - a.score; });
+ hits = hits.slice(0, 25);
+ if (!hits.length) {
+ results.innerHTML = '<div class="search-empty">Nothing in the guide matches that. Try a word you would see on the screen.</div>';
+ return;
}
- return '';
+ var html = '<div class="search-count">' + hits.length + (hits.length === 25 ? '+' : '') + ' result' + (hits.length === 1 ? '' : 's') + '</div>';
+ hits.forEach(function (h) {
+ html += '<a class="search-hit" href="#' + h.e.id + '">'
+ + '<span class="hit-where">' + esc(h.e.where) + '</span>'
+ + '<span class="hit-title">' + esc(h.e.title) + '</span>'
+ + '<span class="hit-snip">' + snippet(h.e, terms) + '</span>'
+ + '</a>';
+ });
+ results.innerHTML = html;
}
- var hero = main.querySelector('.hero');
- if (hero && hero.nextSibling) main.insertBefore(titleEl, hero.nextSibling);
- else main.insertBefore(titleEl, main.firstChild);
- main.appendChild(footer);
+ if (input) {
+ input.addEventListener('input', function () { runSearch(input.value); });
+ input.addEventListener('keydown', function (ev) {
+ if (ev.key === 'Escape') { input.value = ''; runSearch(''); input.blur(); }
+ if (ev.key === 'Enter') {
+ var first = results.querySelector('.search-hit');
+ if (first) { location.hash = first.getAttribute('href'); input.blur(); }
+ }
+ });
+ document.addEventListener('keydown', function (ev) {
+ var typing = /^(INPUT|TEXTAREA|SELECT)$/.test((ev.target && ev.target.tagName) || '');
+ if (ev.key === '/' && !typing) { ev.preventDefault(); input.focus(); input.select(); }
+ if ((ev.key === 'k' || ev.key === 'K') && (ev.metaKey || ev.ctrlKey)) { ev.preventDefault(); input.focus(); input.select(); }
+ });
+ }
+ if (results) {
+ results.addEventListener('click', function (ev) {
+ var a = ev.target.closest && ev.target.closest('.search-hit');
+ if (a) { document.body.classList.remove('nav-open'); }
+ });
+ }
+ // ---- routing ----------------------------------------------------------
function route() {
var id = (location.hash || '').slice(1);
- var chapter = chapterOf[id] || order[0];
- show(chapter, id);
- if (id) {
- var el = document.getElementById(id);
- if (el) el.scrollIntoView({ block: 'start' });
- } else {
- window.scrollTo(0, 0);
+ if (!id || id === 'top') { showFront(); return; }
+ var chapter = chapterOf[id];
+ if (!chapter) {
+ // A hash that is not a section can still be a chapter name.
+ if (order.indexOf(id) >= 0) { show(id, firstIdOf(id)); window.scrollTo(0, 0); return; }
+ showFront(); return;
}
+ show(chapter, id);
+ // A chapter landing page starts at the top of the chapter: scrolling it
+ // "into view" would park its first line under the fixed Contents button.
+ var el = id.indexOf('ch-') === 0 ? null : document.getElementById(id);
+ if (el) el.scrollIntoView({ block: 'start' });
+ else window.scrollTo(0, 0);
+ document.body.classList.remove('nav-open');
}
window.addEventListener('hashchange', route);
route();
+
+ var toggle = document.querySelector('.nav-toggle');
+ if (toggle) toggle.addEventListener('click', function () { document.body.classList.toggle('nav-open'); });
})();
</script>
</body>