atris 3.1.0 → 3.5.0

package/lib/wiki.js

@@ -2,6 +2,9 @@ const fs = require('fs');
 const path = require('path');
 
 const WIKI_ROOT = 'atris/wiki';
+const CONTEXT_ROOT = 'atris/context';
+const PRIVATE_WIKI_ROOT = '.atris/presidio';
+const PRIVATE_CONTEXT_ROOT = `${PRIVATE_WIKI_ROOT}/context`;
 const LEGACY_WIKI_ROOT = 'wiki';
 const WIKI_BRIEFS_SUBDIR = 'briefs';
 const LEGACY_WIKI_BRIEFS_SUBDIR = 'syntheses';
@@ -9,6 +12,18 @@ const WIKI_SUBDIRS = ['people', 'systems', 'concepts', WIKI_BRIEFS_SUBDIR];
 const WIKI_STATUS_FILE = 'STATUS.md';
 const WIKI_CONTENT_SUBDIRS = WIKI_SUBDIRS.map((subdir) => path.join(WIKI_ROOT, subdir));
 
+function getWikiRoot(mode = 'public') {
+  return mode === 'private' ? PRIVATE_WIKI_ROOT : WIKI_ROOT;
+}
+
+function getContextRoot(mode = 'public') {
+  return mode === 'private' ? PRIVATE_CONTEXT_ROOT : CONTEXT_ROOT;
+}
+
+function getWikiLinkRoot(mode = 'public') {
+  return mode === 'private' ? PRIVATE_WIKI_ROOT : 'atris/wiki';
+}
+
 function today() {
   return new Date().toISOString().slice(0, 10);
 }
@@ -17,10 +32,12 @@ function nowTime() {
   return new Date().toTimeString().slice(0, 5);
 }
 
-function protocolMarkdown() {
+function protocolMarkdown(mode = 'public') {
+  const wikiRoot = getWikiRoot(mode);
+  const wikiLinkRoot = getWikiLinkRoot(mode);
   return `# Atris Wiki Protocol
 
-This wiki lives in \`${WIKI_ROOT}/\`.
+This wiki lives in \`${wikiRoot}/\`.
 
 ## Purpose
 
@@ -28,20 +45,20 @@ Turn raw project context into a living memory the next agent can pick up cold.
 
 ## Shape
 
-- \`${WIKI_ROOT}/wiki.md\` - this protocol
-- \`${WIKI_ROOT}/index.md\` - catalog grouped by page type
-- \`${WIKI_ROOT}/log.md\` - append-only ingest and lint history
-- \`${WIKI_ROOT}/STATUS.md\` - plain-English health summary
-- \`${WIKI_ROOT}/people/\` - humans (employees, contacts, stakeholders)
-- \`${WIKI_ROOT}/systems/\` - tools, tables, dashboards, services, products
-- \`${WIKI_ROOT}/concepts/\` - patterns, frameworks, recurring ideas
-- \`${WIKI_ROOT}/${WIKI_BRIEFS_SUBDIR}/\` - multi-page briefs and cross-cutting analysis
+- \`${wikiRoot}/wiki.md\` - this protocol
+- \`${wikiRoot}/index.md\` - catalog grouped by page type
+- \`${wikiRoot}/log.md\` - append-only ingest and lint history
+- \`${wikiRoot}/STATUS.md\` - plain-English health summary
+- \`${wikiRoot}/people/\` - humans (employees, contacts, stakeholders)
+- \`${wikiRoot}/systems/\` - tools, tables, dashboards, services, products
+- \`${wikiRoot}/concepts/\` - patterns, frameworks, recurring ideas
+- \`${wikiRoot}/${WIKI_BRIEFS_SUBDIR}/\` - multi-page briefs and cross-cutting analysis
 
 ## Rules
 
 - Read the full source before writing.
 - Merge new facts into existing pages. Do not overwrite history blindly.
-- Add cross-references with \`[[atris/wiki/...]]\` links.
+- Add cross-references with \`[[${wikiLinkRoot}/...]]\` links.
 - Keep \`index.md\`, \`log.md\`, and \`STATUS.md\` in sync with page changes.
 - If something is unclear or contradictory, say so directly.
 `;
@@ -78,6 +95,23 @@ function statusMarkdown() {
 `;
 }
 
+function contextMarkdown(mode = 'public') {
+  const contextRoot = getContextRoot(mode);
+  const wikiRoot = getWikiRoot(mode);
+  return `# Context
+
+Raw source material lives in \`${contextRoot}/\`.
+Compiled memory belongs in \`${wikiRoot}/\`.
+
+## Rules
+
+- Drop source files or source packs here before compiling them into the wiki.
+- Treat source files as immutable evidence. If the source changes, add a new dated copy.
+- Keep compiled summaries, briefs, and durable facts in the wiki instead of this folder.
+- Use \`${contextRoot}/_ingest/\` for staged ingest packs and receipts.
+`;
+}
+
 function ensureFile(filePath, content) {
   if (!fs.existsSync(filePath)) {
     fs.writeFileSync(filePath, content, 'utf8');
@@ -155,15 +189,18 @@ function migrateLegacyBriefsDir(wikiDir) {
   rewriteLegacyWikiReferences(wikiDir);
 }
 
-function ensureWikiScaffold(projectRoot = process.cwd()) {
-  const wikiDir = path.join(projectRoot, WIKI_ROOT);
+function ensureWikiScaffold(projectRoot = process.cwd(), mode = 'public') {
+  const wikiRoot = getWikiRoot(mode);
+  const wikiDir = path.join(projectRoot, wikiRoot);
   fs.mkdirSync(wikiDir, { recursive: true });
-  migrateLegacyBriefsDir(wikiDir);
+  if (mode === 'public') {
+    migrateLegacyBriefsDir(wikiDir);
+  }
   for (const subdir of WIKI_SUBDIRS) {
     fs.mkdirSync(path.join(wikiDir, subdir), { recursive: true });
   }
 
-  ensureFile(path.join(wikiDir, 'wiki.md'), protocolMarkdown());
+  ensureFile(path.join(wikiDir, 'wiki.md'), protocolMarkdown(mode));
   ensureFile(path.join(wikiDir, 'index.md'), indexMarkdown());
   ensureFile(path.join(wikiDir, 'log.md'), logMarkdown());
   ensureFile(path.join(wikiDir, WIKI_STATUS_FILE), statusMarkdown());
@@ -171,7 +208,128 @@ function ensureWikiScaffold(projectRoot = process.cwd()) {
   return wikiDir;
 }
 
-function findLocalWikiDir(projectRoot = process.cwd(), slug = null) {
+function ensureContextScaffold(projectRoot = process.cwd(), mode = 'public') {
+  const contextRoot = getContextRoot(mode);
+  const contextDir = path.join(projectRoot, contextRoot);
+  fs.mkdirSync(path.join(contextDir, '_ingest'), { recursive: true });
+  ensureFile(path.join(contextDir, 'README.md'), contextMarkdown(mode));
+  return contextDir;
+}
+
+function slugifyLabel(value) {
+  return String(value || 'source')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40) || 'source';
+}
+
+function isInsideDirectory(candidate, rootDir) {
+  const relative = path.relative(rootDir, candidate);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function walkFiles(dir, output = []) {
+  if (!fs.existsSync(dir)) return output;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkFiles(fullPath, output);
+    } else if (entry.isFile()) {
+      output.push(fullPath);
+    }
+  }
+  return output;
+}
+
+function stageWikiIngest(projectRoot = process.cwd(), sourceValue, mode = 'public') {
+  const contextDir = ensureContextScaffold(projectRoot, mode);
+  const ingestDir = path.join(contextDir, '_ingest');
+  const raw = String(sourceValue || '').trim();
+  const timestamp = `${today()}-${nowTime().replace(':', '')}`;
+  const labelSeed = raw ? path.basename(raw) : 'source-pack';
+  const packDir = path.join(ingestDir, `${timestamp}-${slugifyLabel(labelSeed)}`);
+  fs.mkdirSync(packDir, { recursive: true });
+
+  const manifest = {
+    ingested_at: `${today()} ${nowTime()}`,
+    mode,
+    source_input: raw,
+    pack_path: path.relative(projectRoot, packDir).replace(/\\/g, '/'),
+    entries: [],
+  };
+
+  const maybeUrl = /^https?:\/\//i.test(raw);
+  const sourcePath = raw ? path.resolve(projectRoot, raw) : null;
+
+  if (raw && sourcePath && fs.existsSync(sourcePath)) {
+    const stat = fs.statSync(sourcePath);
+    if (isInsideDirectory(sourcePath, contextDir)) {
+      const files = stat.isDirectory() ? walkFiles(sourcePath) : [sourcePath];
+      manifest.entries.push({
+        kind: stat.isDirectory() ? 'directory' : 'file',
+        original: path.relative(projectRoot, sourcePath).replace(/\\/g, '/'),
+        staged: path.relative(projectRoot, sourcePath).replace(/\\/g, '/'),
+        file_count: files.length,
+        files: files.map((filePath) => path.relative(projectRoot, filePath).replace(/\\/g, '/')),
+      });
+    } else {
+      const stagedPath = path.join(packDir, path.basename(sourcePath));
+      if (stat.isDirectory()) {
+        fs.cpSync(sourcePath, stagedPath, { recursive: true });
+      } else {
+        fs.copyFileSync(sourcePath, stagedPath);
+      }
+      const files = stat.isDirectory() ? walkFiles(stagedPath) : [stagedPath];
+      manifest.entries.push({
+        kind: stat.isDirectory() ? 'directory' : 'file',
+        original: path.relative(projectRoot, sourcePath).replace(/\\/g, '/'),
+        staged: path.relative(projectRoot, stagedPath).replace(/\\/g, '/'),
+        file_count: files.length,
+        files: files.map((filePath) => path.relative(projectRoot, filePath).replace(/\\/g, '/')),
+      });
+    }
+  } else if (maybeUrl) {
+    const linksPath = path.join(packDir, 'links.txt');
+    fs.writeFileSync(linksPath, `${raw}\n`, 'utf8');
+    manifest.entries.push({
+      kind: 'url',
+      original: raw,
+      staged: path.relative(projectRoot, linksPath).replace(/\\/g, '/'),
+      file_count: 1,
+      files: [path.relative(projectRoot, linksPath).replace(/\\/g, '/')],
+    });
+  } else {
+    const requestPath = path.join(packDir, 'request.txt');
+    fs.writeFileSync(requestPath, `${raw || '(empty)'}\n`, 'utf8');
+    manifest.entries.push({
+      kind: 'unresolved',
+      original: raw || '(empty)',
+      staged: path.relative(projectRoot, requestPath).replace(/\\/g, '/'),
+      file_count: 1,
+      files: [path.relative(projectRoot, requestPath).replace(/\\/g, '/')],
+    });
+  }
+
+  const manifestPath = path.join(packDir, 'manifest.json');
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+
+  return {
+    contextDir: path.relative(projectRoot, contextDir).replace(/\\/g, '/'),
+    packPath: path.relative(projectRoot, packDir).replace(/\\/g, '/'),
+    manifestPath: path.relative(projectRoot, manifestPath).replace(/\\/g, '/'),
+    promptSource: manifest.entries[0]?.staged || path.relative(projectRoot, packDir).replace(/\\/g, '/'),
+    manifest,
+  };
+}
+
+function findLocalWikiDir(projectRoot = process.cwd(), slug = null, mode = 'public') {
+  if (mode === 'private') {
+    const privateDir = path.join(projectRoot, PRIVATE_WIKI_ROOT);
+    return fs.existsSync(privateDir) ? privateDir : null;
+  }
+
   const tries = [
     path.join(projectRoot, WIKI_ROOT),
     path.join(projectRoot, LEGACY_WIKI_ROOT),
@@ -190,8 +348,8 @@ function normalizeWikiOnlyPrefix(prefix) {
   return null;
 }
 
-function readWikiStatus(projectRoot = process.cwd(), slug = null) {
-  const wikiDir = findLocalWikiDir(projectRoot, slug);
+function readWikiStatus(projectRoot = process.cwd(), slug = null, mode = 'public') {
+  const wikiDir = findLocalWikiDir(projectRoot, slug, mode);
   if (!wikiDir) return null;
 
   const statusPath = path.join(wikiDir, WIKI_STATUS_FILE);
@@ -275,8 +433,9 @@ function parseFrontmatter(content) {
   return frontmatter;
 }
 
-function readWikiPages(projectRoot = process.cwd()) {
-  const wikiDir = path.join(projectRoot, WIKI_ROOT);
+function readWikiPages(projectRoot = process.cwd(), mode = 'public') {
+  const wikiRoot = getWikiRoot(mode);
+  const wikiDir = path.join(projectRoot, wikiRoot);
   const pages = [];
 
   for (const subdir of WIKI_SUBDIRS) {
@@ -302,8 +461,8 @@ function normalizeSourcePath(projectRoot, source) {
   return path.normalize(path.join(projectRoot, source));
 }
 
-function findStaleWikiPages(projectRoot = process.cwd()) {
-  return readWikiPages(projectRoot)
+function findStaleWikiPages(projectRoot = process.cwd(), mode = 'public') {
+  return readWikiPages(projectRoot, mode)
     .map((page) => {
       const sources = Array.isArray(page.frontmatter.sources) ? page.frontmatter.sources : [];
       if (sources.length === 0) return null;
@@ -345,13 +504,14 @@ function findStaleWikiPages(projectRoot = process.cwd()) {
 }
 
 function extractWikiLinks(content) {
-  const matches = content.match(/\[\[(atris\/wiki\/[^\]]+?)\]\]/g) || [];
+  const matches = content.match(/\[\[((?:atris\/wiki|\.atris\/presidio)\/[^\]]+?)\]\]/g) || [];
   return matches.map((match) => match.slice(2, -2));
 }
 
-function findWikiOrphans(projectRoot = process.cwd()) {
-  const pages = readWikiPages(projectRoot);
-  const indexPath = path.join(projectRoot, WIKI_ROOT, 'index.md');
+function findWikiOrphans(projectRoot = process.cwd(), mode = 'public') {
+  const wikiRoot = getWikiRoot(mode);
+  const pages = readWikiPages(projectRoot, mode);
+  const indexPath = path.join(projectRoot, wikiRoot, 'index.md');
   const indexContent = fs.existsSync(indexPath) ? fs.readFileSync(indexPath, 'utf8') : '';
 
   const inboundLinks = new Map();
@@ -423,8 +583,8 @@ function parseStatusBullets(content) {
   return bullets;
 }
 
-function writeWikiStatus(projectRoot = process.cwd(), report) {
-  const wikiDir = ensureWikiScaffold(projectRoot);
+function writeWikiStatus(projectRoot = process.cwd(), report, mode = 'public', overrides = {}) {
+  const wikiDir = ensureWikiScaffold(projectRoot, mode);
   const statusPath = path.join(wikiDir, WIKI_STATUS_FILE);
   const existing = fs.existsSync(statusPath) ? fs.readFileSync(statusPath, 'utf8') : '';
   const bullets = parseStatusBullets(existing);
@@ -432,9 +592,9 @@ function writeWikiStatus(projectRoot = process.cwd(), report) {
   const lines = [
     '# Atris Wiki Status',
     '',
-    `- Last ingest: ${bullets.get('Last ingest') || 'never'}`,
-    `- Last lint: ${bullets.get('Last lint') || 'never'}`,
-    `- Last loop: ${today()} ${nowTime()}`,
+    `- Last ingest: ${overrides.lastIngest || bullets.get('Last ingest') || 'never'}`,
+    `- Last lint: ${overrides.lastLint || bullets.get('Last lint') || 'never'}`,
+    `- Last loop: ${overrides.lastLoop || `${today()} ${nowTime()}`}`,
     `- Health: ${report.health}`,
     `- Next move: ${report.nextMove}`,
     '',
@@ -444,8 +604,8 @@ function writeWikiStatus(projectRoot = process.cwd(), report) {
   return statusPath;
 }
 
-function appendWikiLog(projectRoot = process.cwd(), summary, details = []) {
-  const wikiDir = ensureWikiScaffold(projectRoot);
+function appendWikiLog(projectRoot = process.cwd(), summary, details = [], mode = 'public', kind = 'LOOP') {
+  const wikiDir = ensureWikiScaffold(projectRoot, mode);
   const logPath = path.join(wikiDir, 'log.md');
   let content = fs.existsSync(logPath) ? fs.readFileSync(logPath, 'utf8') : '# Atris Wiki Log\n';
   const dateHeader = `## ${today()}`;
@@ -455,7 +615,7 @@ function appendWikiLog(projectRoot = process.cwd(), summary, details = []) {
   }
 
   if (!content.endsWith('\n')) content += '\n';
-  content += `- ${nowTime()} LOOP ${summary}\n`;
+  content += `- ${nowTime()} ${kind} ${summary}\n`;
   for (const detail of details) {
     content += `  - ${detail}\n`;
   }
@@ -471,17 +631,20 @@ function formatSourceList(sourceValue) {
     .join(', ');
 }
 
-const WIKI_SCHEMA = `The wiki lives in ${WIKI_ROOT}/.
+function buildWikiSchema(mode = 'public') {
+  const wikiRoot = getWikiRoot(mode);
+  const wikiLinkRoot = getWikiLinkRoot(mode);
+  return `The wiki lives in ${wikiRoot}/.
 
 Structure:
-- ${WIKI_ROOT}/wiki.md - protocol for future agents
-- ${WIKI_ROOT}/index.md - catalog grouped by type
-- ${WIKI_ROOT}/log.md - append-only activity log
-- ${WIKI_ROOT}/STATUS.md - plain-English health summary
-- ${WIKI_ROOT}/people/ - one page per human
-- ${WIKI_ROOT}/systems/ - one page per tool, table, dashboard, service, or product
-- ${WIKI_ROOT}/concepts/ - pattern and framework pages
-- ${WIKI_ROOT}/${WIKI_BRIEFS_SUBDIR}/ - cross-cutting briefs referencing 3+ pages
+- ${wikiRoot}/wiki.md - protocol for future agents
+- ${wikiRoot}/index.md - catalog grouped by type
+- ${wikiRoot}/log.md - append-only activity log
+- ${wikiRoot}/STATUS.md - plain-English health summary
+- ${wikiRoot}/people/ - one page per human
+- ${wikiRoot}/systems/ - one page per tool, table, dashboard, service, or product
+- ${wikiRoot}/concepts/ - pattern and framework pages
+- ${wikiRoot}/${WIKI_BRIEFS_SUBDIR}/ - cross-cutting briefs referencing 3+ pages
 
 Page format:
 ---
@@ -497,7 +660,7 @@ tags: [tag1, tag2]
 # Title
 Body in markdown.
 ## Cross-References
-- [[atris/wiki/people/related.md]] - why related
+- [[${wikiLinkRoot}/people/related.md]] - why related
 
 Rules:
 - Read every listed source fully before writing
@@ -505,20 +668,23 @@ Rules:
 - Keep index.md, log.md, and STATUS.md current
 - Flag contradictions directly instead of smoothing them over
 - Never modify the raw source documents you ingested`;
+}
 
-function buildIngestPrompt(sourceValue) {
+function buildIngestPrompt(sourceValue, mode = 'public') {
+  const wikiRoot = getWikiRoot(mode);
+  const wikiLinkRoot = getWikiLinkRoot(mode);
   return `Atris wiki ingest: ${formatSourceList(sourceValue)}
-${WIKI_SCHEMA}
+${buildWikiSchema(mode)}
 
 Workflow:
 1. Read every source in: ${sourceValue}
-2. Ensure ${WIKI_ROOT}/ exists with wiki.md, index.md, log.md, STATUS.md, and the 3 page subfolders
+2. Ensure ${wikiRoot}/ exists with wiki.md, index.md, log.md, STATUS.md, and the 3 page subfolders
 3. Extract people, systems, and concepts worth preserving
-4. Create or update pages under ${WIKI_ROOT}/, merging with existing facts instead of replacing them
-5. Add cross-references using [[atris/wiki/...]] links
-6. Update ${WIKI_ROOT}/index.md with one-line descriptions of touched pages
-7. Append an INGEST entry to ${WIKI_ROOT}/log.md under today's date
-8. Refresh ${WIKI_ROOT}/STATUS.md in plain English for a non-technical reader
+4. Create or update pages under ${wikiRoot}/, merging with existing facts instead of replacing them
+5. Add cross-references using [[${wikiLinkRoot}/...]] links
+6. Update ${wikiRoot}/index.md with one-line descriptions of touched pages
+7. Append an INGEST entry to ${wikiRoot}/log.md under today's date
+8. Refresh ${wikiRoot}/STATUS.md in plain English for a non-technical reader
 
 Quality bar:
 - Ask clarifying questions if the source is ambiguous
@@ -527,18 +693,20 @@ Quality bar:
 - Leave the wiki sharper than you found it`;
 }
 
-function buildQueryPrompt(question) {
+function buildQueryPrompt(question, mode = 'public') {
+  const wikiRoot = getWikiRoot(mode);
   return `Atris wiki query: ${question}
 
-Read ${WIKI_ROOT}/index.md first, then the most relevant pages.
-Answer from the wiki with direct references to page paths under ${WIKI_ROOT}/.
+Read ${wikiRoot}/index.md first, then the most relevant pages.
+Answer from the wiki with direct references to page paths under ${wikiRoot}/.
 If the answer reveals a reusable insight, offer to save it as a brief page.`;
 }
 
-function buildLintPrompt() {
+function buildLintPrompt(mode = 'public') {
+  const wikiRoot = getWikiRoot(mode);
   return `Atris wiki lint pass
 
-Read ${WIKI_ROOT}/index.md, crawl the referenced pages, and inspect the local wiki.
+Read ${wikiRoot}/index.md, crawl the referenced pages, and inspect the local wiki.
 
 Checks:
 1. Every page referenced by index.md exists
@@ -546,8 +714,8 @@ Checks:
 3. Orphan pages are listed
 4. Contradictions are called out plainly
 5. Gaps worth ingesting next are listed concretely
-6. ${WIKI_ROOT}/STATUS.md is rewritten in plain English
-7. ${WIKI_ROOT}/log.md gets a LINT entry under today's date
+6. ${wikiRoot}/STATUS.md is rewritten in plain English
+7. ${wikiRoot}/log.md gets a LINT entry under today's date
 
 Output:
 - Clear summary for a non-technical reader
@@ -557,12 +725,18 @@ Output:
 
 module.exports = {
   WIKI_ROOT,
+  CONTEXT_ROOT,
+  PRIVATE_WIKI_ROOT,
+  PRIVATE_CONTEXT_ROOT,
   LEGACY_WIKI_ROOT,
   WIKI_SUBDIRS,
   WIKI_CONTENT_SUBDIRS,
-  WIKI_SCHEMA,
+  WIKI_SCHEMA: buildWikiSchema(),
   WIKI_STATUS_FILE,
+  getWikiRoot,
+  getContextRoot,
   ensureWikiScaffold,
+  ensureContextScaffold,
   findLocalWikiDir,
   normalizeWikiOnlyPrefix,
   readWikiStatus,
@@ -570,6 +744,7 @@ module.exports = {
   findStaleWikiPages,
   findWikiOrphans,
   findSuggestedSources,
+  stageWikiIngest,
   writeWikiStatus,
   appendWikiLog,
   buildIngestPrompt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atris",
-  "version": "3.1.0",
+  "version": "3.5.0",
   "description": "Atris — an operating system for intelligence. Integrates with any agent.",
   "main": "bin/atris.js",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "bin/",
+    "cli/",
     "commands/",
     "utils/",
     "lib/",
@@ -32,7 +33,8 @@
     "atris/skills/"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "prepare": "cp scripts/pre-commit .git/hooks/pre-commit 2>/dev/null && chmod +x .git/hooks/pre-commit || true"
   },
   "keywords": [
     "atrisdev",

package/utils/api.js

@@ -20,22 +20,41 @@ try {
 const DEFAULT_CLIENT_ID = `AtrisCLI/${CLI_VERSION}`;
 const DEFAULT_USER_AGENT = `${DEFAULT_CLIENT_ID} (node ${process.version}; ${os.platform()} ${os.release()} ${os.arch()})`;
 
+/**
+ * Get the base URL for the Atris API.
+ * @returns {string} API base URL
+ */
 function getApiBaseUrl() {
   const raw = process.env.ATRIS_API_URL || 'https://api.atris.ai/api';
   return raw.replace(/\/$/, '');
 }
 
+/**
+ * Get the base URL for the Atris web app.
+ * @returns {string} App base URL
+ */
 function getAppBaseUrl() {
   const raw = process.env.ATRIS_APP_URL || 'https://atris.ai';
   return raw.replace(/\/$/, '');
 }
 
+/**
+ * Build a full API URL from a path.
+ * @param {string} pathname - API endpoint path
+ * @returns {string} Full API URL
+ */
 function buildApiUrl(pathname) {
   const base = getApiBaseUrl();
   const normalizedPath = pathname.startsWith('/') ? pathname : `/${pathname}`;
   return `${base}${normalizedPath}`;
 }
 
+/**
+ * Make an HTTP/HTTPS request.
+ * @param {string} urlString - Full URL to request
+ * @param {Object} options - Request options (method, headers, body, timeoutMs)
+ * @returns {Promise<Object>} Response with statusCode, headers, and data
+ */
 function httpRequest(urlString, options) {
   return new Promise((resolve, reject) => {
     const parsed = new URL(urlString);

package/utils/auth.js

@@ -4,6 +4,10 @@ const fs = require('fs');
 const { exec } = require('child_process');
 const readline = require('readline');
 
+/**
+ * Open a URL in the system's default browser.
+ * @param {string} url - URL to open
+ */
 function openBrowser(url) {
   const platform = os.platform();
   // Sanitize URL to prevent shell injection — only allow valid URL characters
@@ -30,6 +34,11 @@ let sharedRl = null;
 let inputLines = [];
 let inputIndex = 0;
 
+/**
+ * Prompt the user for input, handling both TTY and piped input.
+ * @param {string} question - Prompt text to display
+ * @returns {Promise<string>} User's input
+ */
 function promptUser(question) {
   // If stdin is not a TTY (piped input), read all lines upfront
   if (!process.stdin.isTTY && inputLines.length === 0 && !sharedRl) {
@@ -74,7 +83,11 @@ function promptUser(question) {
 
 const TOKEN_REFRESH_BUFFER_SECONDS = 300;
 
-// JWT helpers
+/**
+ * Decode and parse the claims from a JWT token.
+ * @param {string} token - JWT token string
+ * @returns {Object|null} Decoded claims or null if invalid
+ */
 function decodeJwtClaims(token) {
   if (!token || typeof token !== 'string') {
     return null;
@@ -93,6 +106,11 @@ function decodeJwtClaims(token) {
   }
 }
 
+/**
+ * Get the expiration time of a JWT token in epoch seconds.
+ * @param {string} token - JWT token string
+ * @returns {number|null} Expiry epoch seconds or null if invalid
+ */
 function getTokenExpiryEpochSeconds(token) {
   const claims = decodeJwtClaims(token);
   if (!claims || typeof claims.exp !== 'number') {
@@ -101,6 +119,12 @@ function getTokenExpiryEpochSeconds(token) {
   return claims.exp;
 }
 
+/**
+ * Check if a JWT token should be refreshed based on expiry.
+ * @param {string} token - JWT token string
+ * @param {number} [bufferSeconds=300] - Seconds before expiry to trigger refresh
+ * @returns {boolean} True if token needs refresh
+ */
 function shouldRefreshToken(token, bufferSeconds = TOKEN_REFRESH_BUFFER_SECONDS) {
   const exp = getTokenExpiryEpochSeconds(token);
   if (!exp) {

package/utils/config.js

@@ -1,11 +1,19 @@
 const fs = require('fs');
 const path = require('path');
 
+/**
+ * Get the path to atris/.config in the current project.
+ * @returns {string} Config file path
+ */
 function getConfigPath() {
   const targetDir = path.join(process.cwd(), 'atris');
   return path.join(targetDir, '.config');
 }
 
+/**
+ * Load config from atris/.config, returning empty object if missing/invalid.
+ * @returns {Object} Config object
+ */
 function loadConfig() {
   const configPath = getConfigPath();
 
@@ -21,6 +29,10 @@ function loadConfig() {
   }
 }
 
+/**
+ * Save config to atris/.config. Exits if atris/ folder doesn't exist.
+ * @param {Object} config - Config object to save
+ */
 function saveConfig(config) {
   const configPath = getConfigPath();
   const targetDir = path.dirname(configPath);
@@ -33,11 +45,19 @@ function saveConfig(config) {
   fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
 }
 
+/**
+ * Get the path to atris/.log_sync_state.json for tracking sync timestamps.
+ * @returns {string} Log sync state file path
+ */
 function getLogSyncStatePath() {
   const targetDir = path.join(process.cwd(), 'atris');
   return path.join(targetDir, '.log_sync_state.json');
 }
 
+/**
+ * Load log sync state, returning empty object if missing/invalid.
+ * @returns {Object} Sync state object with last sync timestamps
+ */
 function loadLogSyncState() {
   const statePath = getLogSyncStatePath();
   if (!fs.existsSync(statePath)) {
@@ -51,6 +71,10 @@ function loadLogSyncState() {
   }
 }
 
+/**
+ * Save log sync state to atris/.log_sync_state.json.
+ * @param {Object} state - Sync state object to save
+ */
 function saveLogSyncState(state) {
   const statePath = getLogSyncStatePath();
   fs.writeFileSync(statePath, JSON.stringify(state, null, 2));