Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/** Canonical install/source roots and path construction helpers. */
import { homedir } from 'os';
import { join } from 'path';
import { resolveCodeRootForModule, resolveInstallRoot } from './dataRoot.js';
// The executing checkout's root (where THIS file physically lives). Code/source
// paths — the repo root for git ops, `lib/slashdo` — must stay anchored here so
// they always point at the checkout that loaded the code.
const CODE_ROOT = resolveCodeRootForModule(import.meta.url);
// The install root that holds the runtime `data/` tree. Prefer an explicit
// PORTOS_DATA_ROOT env var over the executing-file location so a process booted
// from inside a CoS agent git worktree resolves `data/` to the real install
// instead of the worktree's empty checkout (#1947). Falls back to CODE_ROOT
// when the env var is unset (the two coincide for a normal install). Only
// `data/*` paths follow this — source/git paths stay on CODE_ROOT.
const INSTALL_ROOT = resolveInstallRoot(CODE_ROOT);
/**
* Base directories relative to project root
*/
export const PATHS = {
root: CODE_ROOT,
// The data-bearing install root (parent of `data/`). Equals `root` for a
// normal install; diverges only when PORTOS_DATA_ROOT pins a different tree
// (worktree boot, #1947). Use this — not `root` — for anything anchored to
// the `data/` tree but living one level above it (e.g. the migration ledger
// `data/migrations.applied.json`), so its reader agrees with where boot wrote it.
installRoot: INSTALL_ROOT,
data: join(INSTALL_ROOT, 'data'),
cos: join(INSTALL_ROOT, 'data/cos'),
brain: join(INSTALL_ROOT, 'data/brain'),
digitalTwin: join(INSTALL_ROOT, 'data/digital-twin'),
health: join(INSTALL_ROOT, 'data/health'),
runs: join(INSTALL_ROOT, 'data/runs'),
memory: join(INSTALL_ROOT, 'data/cos/memory'),
cosAgents: join(INSTALL_ROOT, 'data/cos/agents'), // CoS sub-agents
scripts: join(INSTALL_ROOT, 'data/cos/scripts'),
reports: join(INSTALL_ROOT, 'data/cos/reports'),
// AI Agent Personalities data
agentPersonalities: join(INSTALL_ROOT, 'data/agents'),
meatspace: join(INSTALL_ROOT, 'data/meatspace'),
calendar: join(INSTALL_ROOT, 'data/calendar'),
messages: join(INSTALL_ROOT, 'data/messages'),
screenshots: join(INSTALL_ROOT, 'data/screenshots'),
uploads: join(INSTALL_ROOT, 'data/uploads'),
cosAttachments: join(INSTALL_ROOT, 'data/cos/attachments'),
worktrees: join(INSTALL_ROOT, 'data/cos/worktrees'),
repos: join(INSTALL_ROOT, 'data/repos'),
browserProfile: join(INSTALL_ROOT, 'data/browser-profile'),
browserDownloads: join(homedir(), 'Downloads'),
digests: join(INSTALL_ROOT, 'data/cos/digests'),
promptSkills: join(INSTALL_ROOT, 'data/prompts/skills'),
promptSkillsJobs: join(INSTALL_ROOT, 'data/prompts/skills/jobs'),
decisions: join(INSTALL_ROOT, 'data/cos/decisions'),
telegram: join(INSTALL_ROOT, 'data/telegram'),
templates: join(INSTALL_ROOT, 'data/prompts/templates'),
// Visual template assets (e.g. the character reference-sheet layout PNG used
// as the init-image anchor by the universe-builder character sheet renderer).
// Distinct from `templates` above, which is the legacy prompt-template dir.
// Files here are shipped via data.reference/templates/ on first install.
visualTemplates: join(INSTALL_ROOT, 'data/templates'),
settings: join(INSTALL_ROOT, 'data/settings'),
tools: join(INSTALL_ROOT, 'data/tools'),
images: join(INSTALL_ROOT, 'data/images'),
// Uploaded multi-reference inputs for FLUX.2 multi-ref edits. Sibling of
// `images/` rather than a subdir so the gallery's flat `.png` enumeration
// never surfaces them, and so a future per-render cleanup pass can drop
// the whole dir without touching the gallery.
imageRefs: join(INSTALL_ROOT, 'data/image-refs'),
// Ephemeral working dir for the Image Cleaner's GPU FLUX round-trip (issue
// #2264). The sync-cleaned init bytes and the finished render land here as
// `<jobId>-init.png` / `<jobId>-result.png` so the cleaner can render WITHOUT
// writing a gallery file + sidecar (the default is not to keep the result).
// A sibling of `images/` — never surfaced by the gallery's flat `.png`
// enumeration; swept by imageCleanTmpGc.js on an age gate. Not federated.
imageCleanTmp: join(INSTALL_ROOT, 'data/image-clean-tmp'),
// PROVIDER-side staging for conditioning images an allowlisted peer uploaded
// ahead of a federated render (ADR
// docs/decisions/2026-08-22-federated-media-input-assets.md rule 1). Files are
// named `<callerHash>-<sha256>.<ext>` and swept on a TTL.
//
// Deliberately its own root rather than a corner of `images/` or `uploads/`:
// these are ANOTHER machine's bytes, held briefly to run one job. Under
// `images/` the gallery would enumerate them and the sync layer would federate
// them onward (the failure this repo already hit once with temp files in
// data/images). Excluded from backups for the same reason — restoring a peer's
// half-hour-old init image is worth nothing.
federatedMediaInbox: join(INSTALL_ROOT, 'data/federated-media-inbox'),
loras: join(INSTALL_ROOT, 'data/loras'),
// Per-character LoRA training datasets (collectionStore layout:
// lora-datasets/<id>/index.json + lora-datasets/<id>/images/*.png).
// Machine-local like `loras/` — datasets never federate.
loraDatasets: join(INSTALL_ROOT, 'data/lora-datasets'),
rapidReaderLibrary: join(INSTALL_ROOT, 'data/rapid-reader-library'),
// LoRA training run artifacts (checkpoints/samples/cache per run). Run
// RECORDS live in Postgres (lora_training_runs); only artifacts live here.
trainingRuns: join(INSTALL_ROOT, 'data/training-runs'),
// Character voice-profile metadata lives in PostgreSQL; this directory holds
// the local benchmark WAVs and future engine artifacts referenced by it.
// It deliberately stays machine-local and is included in normal data backups.
voiceProfiles: join(INSTALL_ROOT, 'data/voice-profiles'),
videos: join(INSTALL_ROOT, 'data/videos'),
videoThumbnails: join(INSTALL_ROOT, 'data/video-thumbnails'),
// Music Video cover lettering (#10345): typefaces the director uploaded (.ttf/.otf/.woff2)
// plus their index. Machine-local; included in normal data backups.
coverFonts: join(INSTALL_ROOT, 'data/cover-fonts'),
imageThumbnails: join(INSTALL_ROOT, 'data/image-thumbnails'),
// Sprite Manager (issue #2895): per-record asset trees
// (sprites/<id>/{reference,walk,runs,runtime,atlas}/...). Records live in
// Postgres (sprite_records); only binary artifacts + manifests live here.
sprites: join(INSTALL_ROOT, 'data/sprites'),
// Image-to-3D (issue #2952): per-record GLB meshes rendered locally by a
// target (TRELLIS.2 today), stored as image-to-3d/<id>/model.glb. Records
// live in Postgres (image_to_3d_models); only the binary GLB lives here.
imageTo3d: join(INSTALL_ROOT, 'data/image-to-3d'),
// Persisted audio renders (voice-over lines). Kept distinct from
// the in-memory voice-agent synthesis path in services/voice/ — that path
// streams WAV over Socket.IO without ever touching disk.
audio: join(INSTALL_ROOT, 'data/audio'),
// Uploaded + (eventually) generated background music tracks. Separate from
// `audio/` so the user can browse + reuse a track across issues without
// walking through the VO-line filenames.
music: join(INSTALL_ROOT, 'data/music'),
// Extracted assets from third-party imports (ChatGPT export images/audio/
// PDFs). Served read-only at `/data/brain-imports/...` so the Memory
// conversation viewer can render inline `` images and asset links.
// Flat per-source dir keyed by the asset's globally-unique id, so the same
// asset referenced from multiple conversations is stored once. The transcript
// archive JSON lives one level up (data/brain/imports/<source>/) and is NOT
// served — only this assets subtree is.
brainImportAssets: join(INSTALL_ROOT, 'data/brain/imports/assets'),
// SongBook attachment BYTES (PDF sheet music, images, MIDI). Machine-local —
// only the metadata syncs inside the brain `songs` record; peers lacking a
// file render "not on this machine". Covered by backup via data/brain/.
brainSongbook: join(INSTALL_ROOT, 'data/brain/songbook'),
// Beeper attachment BYTES (#37) — content-addressed as
// `<sha256[0..2]>/<sha256>.<ext>`, mirrored lazily on first human view and
// bounded by `settings.beeper.attachmentBudgetGb`. Machine-local and never
// federated, like every other Beeper mirror row; excluded from backups by
// default (overridable) because it is re-fetchable from Beeper for as long
// as the source network still holds the media, and the mirror renders the
// reference when it does not.
beeperAttachments: join(INSTALL_ROOT, 'data/beeper/attachments'),
slashdo: join(CODE_ROOT, 'lib/slashdo'),
// Fully-resolved slashdo command bodies written for CoS agents to READ on
// demand instead of receiving them pasted into the prompt (issue #3110).
// Derived cache, never authored: regenerated on first use each process, safe
// to delete. Anchored to INSTALL_ROOT (not CODE_ROOT) because the pointer
// handed to an agent must name a path that exists on the running install.
slashdoResolved: join(INSTALL_ROOT, 'data/cos/slashdo-resolved')
};
/**
* Get a path relative to the data directory.
*
* @param {...string} segments - Path segments to join
* @returns {string} Full path under data directory
*
* @example
* const filePath = dataPath('cos', 'state.json');
* // Returns: /path/to/project/data/cos/state.json
*/
export function dataPath(...segments) {
return join(PATHS.data, ...segments);
}
// `path.join(homedir(), '/.foo')` discards the homedir prefix because of
// the leading slash, so strip the leading `~/` (or `~\` on Windows) before
// joining. Only expands a leading `~` — embedded `~` chars in path segments
// (e.g. `iCloud~md~obsidian`) are preserved.
export function expandHome(p) {
if (typeof p !== 'string' || !p) return p;
if (p === '~') return homedir();
if (p.startsWith('~/') || p.startsWith('~\\')) return join(homedir(), p.slice(2));
return p;
}