Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 64 additions & 0 deletions docs/AGENT-FIRST-VALIDATION.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# Agent-first onboarding and installed SB validation

2026-11-13. Baseline: `5aade2bbd37ec2aaccb89e56b254fee05573686e`, published SB 0.2.6.

## Product correction

KeepMind SB is shared context for agents in the user's AI application. The primary onboarding action now opens agent integration instructions. It neither configures the internal chat provider nor requires a manual note/password. Today and the personal desktop/compact navigation prioritize connections; memory empty states explain agent-generated context. Manual capture remains an optional utility accessible from Memory and its existing shortcut.

Opening instructions does **not** establish or verify a connection. Existing MCP/GitHub configuration, encryption, authorization and recovery remain enforced. Protection is configured through Settings. Removing it from onboarding does not unlock a vault or migrate data. Internal chat AI remains optional in Settings.

## Installed native app

Tested a disposable copy of the installed app, with matching `app.asar` SHA-256 `76afdfc16c459c7ece6004e5795ca28d6bacfcf9ab1a7349814ba9668a42813e`. Main-process assertions verified the effective temporary user-data directory before inputs. Synthetic account, project and encrypted source only. Keychain storage was replaced with an in-memory test store; OS Keychain integration was not tested.

Observed through macOS accessibility/UI automation:

- Invalid login rejected; valid synthetic login opened Today. Found raw Electron IPC error text on invalid credentials. Fixed with a Portuguese actionable alert and retry regression test.
- Today → resume project retained objective, next step and accepted decision.
- Project → source opened the full original synthetic source with path and history warning.
- Returning to Projects retained the selected project. Resume context → use in conversation prepared a draft without sending it to an AI provider.
- Native navigation responded without observed stalls. No FPS benchmark or long-session performance claim.

Isolation limitation: before the fixed-profile launcher was installed, macOS launched the test copy twice without its intended profile arguments. Both were stopped before clicks/typing. No personal content was intentionally edited, but those launches may have updated caches; byte-for-byte preservation of the personal profile is **not** claimed. Subsequent inputs were confined to the verified disposable profile. The installed app bundle was not modified by these tests.

## Changed renderer validation

- Build and TypeScript passed.
- Vitest: 305 passed, 2 existing skips.
- Existing `npm run test:experience` extended, 11 journeys passed: navigation, draft/error/retry, project resume, full source, answer source, reduced motion/avatar preference, keyboard focus, responsive onboarding and actual onboarding-to-integrations route.
- Header/footer/action visibility checked at 1440×900, 1024×640 and 390×844. Rendered preview inspected visually through CUA; compact screenshot reviewed separately. Main content scrolls; actions remain reachable.
- Security component tests still require recovery acknowledgement and preserve credentials after an unlock failure. No crypto gate removed.
- Corp brain build/selfcheck, CRM browser batch and release gate/report checks passed.
- Jev advisory review (`jev-1.14.0`, 1879 input/78 output tokens) found agent-first focus and honest instruction-vs-connection wording, each choice probability 1.0. This is not proof of functionality; report retained.

An initial smoke run used the old built renderer; rebuilt before successful rerun. An older app test expected the removed primary Capture button; updated to exercise the retained capture shortcut. No production AI connection, real credentials, email, or external agent writes were tested. New changes were validated in the renderer, not installed over the user's application.

## Reproduce

Reuse the existing batch rather than a new runner:

```sh
npm run build
npm run typecheck
TMPDIR=/private/tmp npm test
npm run test:experience
npm run corp:build-brain
npm run corp:check
TMPDIR=/private/tmp npm run test:crm-browser
node scripts/check-release-gates.mjs --reports
```

Aggregate report: [experience-report.json](evidence/agent-first/experience-report.json).

![Agent-first onboarding](evidence/agent-first/onboarding-desktop.png)

![Compact onboarding](evidence/agent-first/onboarding-compact.png)

## Default neural background (PR #22 follow-up)

Neurons are enabled by default for profiles without a saved background preference. An explicit saved opt-out is preserved. Rendering is capped at 30 fps (including 120 Hz displays), with at most 96 neurons and 20 simultaneous pulses. Slower drift/pulses, clamped activity boost and 34% canvas opacity keep decoration subordinate to text/cards. Neighbor recomputation runs at most once per 600 ms. Hidden documents pause the loop; reduced motion or disabling the background removes it and releases the frame/resize work.

Validation: build/typecheck passed; 307 unit tests passed, two existing skips. The extended experience batch passed 12 journeys, including actual canvas content changing, non-intercepting pointer events, navigation with animation enabled, and canvas removal under system reduced motion. A deterministic 120 Hz simulation asserts no more than 30 canvas draws per second, pause/resume and cleanup. Visual review of the synthetic Today renderer confirmed visible, subdued neurons and readable cards. This is not a hardware FPS/battery benchmark; no change was installed into the user's personal app/profile.

![Default neural background](evidence/agent-first/neurons-background.png)
54 changes: 54 additions & 0 deletions docs/evidence/agent-first/experience-report.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
{
"fixture": "synthetic in-memory demo; no external services",
"checks": [
{
"name": "Hoje and five primary destinations",
"result": "passed"
},
{
"name": "Default neural background animates without intercepting navigation and honors reduced motion",
"result": "passed"
},
{
"name": "Capture failure, draft and retry",
"result": "passed"
},
{
"name": "Memory search failure, retry and full source",
"result": "passed"
},
{
"name": "Project continuation and screenshot",
"result": "passed"
},
{
"name": "Chat running and cancellation",
"result": "passed"
},
{
"name": "Reduced motion and avatar preference",
"result": "passed"
},
{
"name": "Relacionamentos navigation",
"result": "passed"
},
{
"name": "Rotinas navigation",
"result": "passed"
},
{
"name": "Narrow viewport navigation and focus",
"result": "passed"
},
{
"name": "Answer evidence opens original memory without losing the conversation",
"result": "passed"
},
{
"name": "Onboarding keeps header and actions reachable at desktop and narrow sizes",
"result": "passed"
}
],
"errors": []
}
Binary file added docs/evidence/agent-first/neurons-background.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/evidence/agent-first/onboarding-compact.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/evidence/agent-first/onboarding-desktop.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
46 changes: 46 additions & 0 deletions docs/evidence/agent-first/semantic-review.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
{
"summary": {
"requested": 1,
"completed": 1,
"failed": 0,
"skipped": 0,
"input_tokens": 1879,
"output_tokens": 78
},
"results": [
{
"index": 0,
"ok": true,
"attempts": 1,
"seconds": 0.293,
"response": {
"model": "jev-1.14.0",
"answers": {
"agent_focus": {
"type": "choice",
"choice": "yes",
"confidence": 1.0,
"probabilities": {
"yes": 1.0,
"no": 0.0
}
},
"connection_claim": {
"type": "choice",
"choice": "honest_instructions",
"confidence": 1.0,
"probabilities": {
"claims_connected": 0.0,
"honest_instructions": 1.0,
"unclear": 0.0
}
}
},
"usage": {
"input_tokens": 1879,
"output_tokens": 78
}
}
}
]
}
31 changes: 27 additions & 4 deletions scripts/experience-smoke.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,9 @@ try {
const unsubscribe = () => () => {}
const bridge = {
getConfig: async () => config,
setConfig: async patch => { Object.assign(config, patch); return config },
mcpStatus: async () => ({ running: [], allTools: [] }),
connectInfo: async () => ({ mcpScript: '/synthetic/keepmind-mcp.mjs', memoryDir: '/synthetic/memory', repoUrl: null }),
crm: async action => { if (action !== 'snapshot') throw Error('Prévia somente leitura'); return { revision:0,space:'synthetic',contacts:[],interactions:[],commitments:[],opportunities:[],drafts:[],settings:{commercialEnabled:false,autoPrepare:true,allowAutomaticSend:false},insights:[],duplicates:[],merges:[],capabilities:{canWrite:false,canConfigure:false,canSend:false,boards:[{id:'personal',label:'Prévia'}]} } },
authState: async () => ({ needsSetup: false, user: { id: 'synthetic', name: 'Demo', email: 'demo@example.invalid' } }),
memorySecurityStatus: async () => ({ space: 'personal', configured: true, unlocked: true }),
Expand Down Expand Up @@ -74,8 +77,23 @@ try {
await page.getByText('Projeto sintético', { exact: true }).first().waitFor()
await page.screenshot({ path: `${artifacts}/desktop-hoje.png`, fullPage: true })
})
await check('Default neural background animates without intercepting navigation and honors reduced motion', async () => {
await page.emulateMedia({ reducedMotion: 'no-preference' })
const field = page.locator('canvas.neural-field')
await field.waitFor()
assert.equal(await field.getAttribute('aria-hidden'), 'true')
assert.equal(await field.evaluate(el => getComputedStyle(el).pointerEvents), 'none')
const first = await field.evaluate(el => el.toDataURL())
// Wait for actual changed canvas content, not simply a mounted blank canvas.
await page.waitForFunction(first => document.querySelector('canvas.neural-field')?.toDataURL() !== first, first)
await go('Memória'); await go('Hoje')
await page.getByRole('heading', { name: 'Continue de onde parou' }).waitFor()
await page.screenshot({path:`${artifacts}/neural-background.png`})
await page.emulateMedia({ reducedMotion: 'reduce' })
await field.waitFor({state:'detached'})
})
await check('Capture failure, draft and retry', async () => {
await page.locator('.sidebar-capture').click()
await page.keyboard.press('Control+Shift+m')
const dialog = page.getByRole('dialog', { name: 'Capturar uma ideia' })
const field = dialog.getByLabel('O que você quer lembrar?')
assert.equal(await field.evaluate(el => el === document.activeElement), true)
Expand Down Expand Up @@ -214,19 +232,24 @@ try {
assert(bounds.header.top >= 0 && bounds.footer.bottom <= height + 1, `Header/footer clipped at ${width}x${height}: ${JSON.stringify(bounds)}`)
assert(bounds.heading.top >= bounds.main.top && bounds.heading.bottom <= bounds.main.bottom, 'Heading clipped')
assert(!bounds.overflow, 'Horizontal overflow')
for (const name of ['Voltar','Configurar depois','Configurar e continuar']) {
for (const name of ['Voltar','Explorar primeiro','Conectar meus agentes']) {
const box = await page.getByRole('button',{name,exact:true}).boundingBox()
assert(box && box.y >= 0 && box.y + box.height <= height + 1 && box.x >= 0 && box.x + box.width <= width + 1, `Action outside viewport: ${name}`)
}
await page.screenshot({path:`${artifacts}/onboarding-${width}x${height}.png`})
}
const focused = new Set()
for(let i=0;i<24;i++){await page.keyboard.press('Tab');focused.add(await page.evaluate(()=>document.activeElement?.textContent?.trim()))}
for(const name of ['Voltar','Configurar depois','Configurar e continuar'])assert(focused.has(name),`Keyboard cannot reach ${name}`)
for(const name of ['Voltar','Explorar primeiro','Conectar meus agentes'])assert(focused.has(name),`Keyboard cannot reach ${name}`)
await page.emulateMedia({reducedMotion:'reduce'})
assert.equal(await page.locator('.wizard').evaluate(el=>getComputedStyle(el).animationName),'none')
await page.getByRole('button',{name:'Configurar depois',exact:true}).click()
await page.getByRole('button',{name:'Voltar',exact:true}).click()
assert.equal(await page.evaluate(()=>document.activeElement?.id),'wizard-title')
await page.getByRole('button',{name:'Começar →',exact:true}).click()
assert.equal(await page.locator('textarea,input[type=password]').count(),0)
await page.getByRole('button',{name:'Conectar meus agentes',exact:true}).click()
await page.getByRole('heading',{name:'Conecte seus agentes',exact:true}).waitFor()
await page.getByRole('heading',{name:'Cursor Composer',exact:true}).waitFor()
})
assert.deepEqual(errors, [], `Browser errors: ${errors.join('; ')}`)
} catch (error) {
Expand Down
8 changes: 4 additions & 4 deletions src/renderer/src/App.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -163,7 +163,7 @@ export default function App() {
return () => { window.removeEventListener('keydown', onKey); offCapture?.() }
}, [config?.onboardingDone, authState?.user, dialog])

const ready = async (intent?: { view: 'chat' | 'graph' | 'memory' | 'settings'; query?: string; path?: string }) => {
const ready = async (intent?: { view: 'chat' | 'graph' | 'memory' | 'settings' | 'connectors'; query?: string; path?: string }) => {
await loadConfig()
if (intent) navigate(intent.view === 'graph' ? 'memory' : intent.view, { query: intent.query, path: intent.path })
}
Expand All @@ -188,16 +188,16 @@ export default function App() {
{view !== 'graph' && <NeuralField activity={activity} />}
<aside className="sidebar">
<button className="brand brand-button" onClick={() => navigate('today')} aria-label="KeepMind SB — início"><BrainMark size={34} /><span className="brand__text"><span className="brand__name">keep<em>mind</em> SB</span><span className="brand__tag">Seu contexto, sempre com você</span></span></button>
<button className="btn btn--primary sidebar-capture" onClick={() => setDialog('capture')} title="Capturar · Ctrl / ⌘ + Shift + M"><IconPlus size={18} /><span>Capturar</span></button>
<button className="btn btn--primary sidebar-capture" onClick={() => corp ? setDialog('capture') : navigate('connectors')}><IconPlug size={18} /><span>{corp ? 'Capturar' : 'Conectar agentes'}</span></button>
<nav className="nav" aria-label="Navegação principal"><div className="nav__group">{primary.map(n => <button key={n.id} className={`nav__item ${primaryView === n.id ? 'is-active' : ''}`} onClick={() => navigate(n.id)} aria-current={primaryView === n.id ? 'page' : undefined} aria-label={n.label} title={n.label}><span className="ico" aria-hidden="true"><n.Icon size={19} /></span><span className="nav__label">{n.label}</span>{n.id === 'automations' && pendingCount !== null && pendingCount > 0 && <span className="nav__badge">{pendingCount}</span>}</button>)}</div></nav>
<div className="sidebar__foot"><button className={`nav__item${!PRIMARY.some(n => n.id === primaryView) ? ' is-active' : ''}`} onClick={() => setDialog('tools')} title="Ferramentas e configurações" aria-label="Ferramentas e configurações"><span className="ico" aria-hidden="true"><IconSettings size={19} /></span><span className="nav__label">Ferramentas</span></button><button className="status-pill" onClick={() => navigate('settings')} title={`Modelo configurado: ${config.ai?.provider ?? 'nenhum'}`}><span className="status-pill__text">Modelo · {config.ai?.provider ?? 'Configurar'}</span></button><div className="sidebar-status" title={jobLine}><span className={`status-dot${job?.phase === 'start' ? ' is-working' : job?.phase === 'error' ? ' has-error' : ''}`} /><span>{jobLine}</span></div></div>
</aside>
<div className="app-workspace"><header className="app-toolbar"><div className="app-breadcrumb"><span>KeepMind SB</span><span aria-hidden="true">/</span><strong>{label}</strong></div><div className="toolbar-actions"><button className="toolbar-search" onClick={() => setDialog('search')} aria-label="Buscar na memória e navegar"><span>Buscar</span><kbd>⌘ / Ctrl K</kbd></button><button aria-label="Capturar uma ideia" className="btn btn--sm toolbar-capture" onClick={() => setDialog('capture')}><IconPlus size={16} /><span>Capturar</span></button><button className="icon-button toolbar-tools" onClick={() => setDialog('tools')} aria-label="Ferramentas e configurações"><IconSettings size={19} /></button></div></header>
<div className="app-workspace"><header className="app-toolbar"><div className="app-breadcrumb"><span>KeepMind SB</span><span aria-hidden="true">/</span><strong>{label}</strong></div><div className="toolbar-actions"><button className="toolbar-search" onClick={() => setDialog('search')} aria-label="Buscar na memória e navegar"><span>Buscar</span><kbd>⌘ / Ctrl K</kbd></button><button aria-label={corp ? 'Capturar uma ideia' : 'Conectar agentes'} className="btn btn--sm toolbar-capture" onClick={() => corp ? setDialog('capture') : navigate('connectors')}><IconPlug size={16} /><span>{corp ? 'Capturar' : 'Conectar'}</span></button><button className="icon-button toolbar-tools" onClick={() => setDialog('tools')} aria-label="Ferramentas e configurações"><IconSettings size={19} /></button></div></header>
{vaultLocked && <div className="lock-status" role="status"><span>Desbloqueie sua memória para guardar e consultar informações.</span><button className="btn btn--sm" onClick={() => navigate('settings')}>Desbloquear</button></div>}
{(window as any).__KEEPMIND_DEMO__ && <div className="demo-status">Prévia com dados fictícios. Use o aplicativo para guardar sua memória.</div>}
<main className="main" id="app-content" tabIndex={-1} aria-label={label}>
<Suspense fallback={<div className="view" role="status">Abrindo {label.toLowerCase()}…</div>}>
{view === 'today' && <Today key={sessionKey} refreshToken={dataVersion} onToast={toast} onNavigate={navigateToday} onCapture={() => setDialog('capture')} />}
{view === 'today' && <Today personal={!corp} key={sessionKey} refreshToken={dataVersion} onToast={toast} onNavigate={navigateToday} onCapture={() => setDialog('capture')} />}
{visited.includes('projects') && <div className="retained-view" hidden={view !== 'projects'} key={`projects:${sessionKey}`}><Projects onOpenSource={path => navigate('memory', { path })} unsupported={!!corp} initialProjectId={projectId} initialProjectRequest={projectRequest} onResume={text => navigate('chat', { query: text })} /></div>}
{visited.includes('relationships') && <div className="retained-view" hidden={view !== 'relationships'} key={`relationships:${sessionKey}`}><Relationships active={view === 'relationships'} refreshToken={dataVersion} initialContactId={contactId} initialRequest={contactRequest} onAsk={text => navigate('chat', { query: text })} onOpenSource={path => navigate('memory', { path })} /></div>}
{visited.includes('chat') && <div className="retained-view" hidden={view !== 'chat'} key={`chat:${sessionKey}`}><Chat onActivity={pulse} active={view === 'chat'} sessionKey={sessionKey} initialPrompt={chatPrompt} onOpenMemory={path => navigate('memory', { path })} /></div>}
Expand Down
Loading
Loading