feat: support configurable OpenWiki state directory

README.md

@@ -106,7 +106,98 @@ openwiki ingest web-search  # run one connector's sources
 <details>
 <summary><b>Connector details and OAuth</b></summary>
 
-<br/>
+```sh
+openwiki -p "Summarize what you can do"
+```
+
+Initialize OpenWiki:
+
+```sh
+openwiki personal --init
+```
+
+Initialize repository code documentation:
+
+```sh
+openwiki code --init
+```
+
+Update existing documentation:
+
+```sh
+openwiki --update
+```
+
+Update repository code documentation:
+
+```sh
+openwiki code --update
+```
+
+Run an update that can ingest configured local connectors first:
+
+```sh
+openwiki --update "Refresh the wiki from configured connectors"
+```
+
+Show help:
+
+```sh
+openwiki --help
+```
+
+In chat, use `/api-key` to update the current provider API key and
+`/langsmith-key` to update or clear LangSmith tracing credentials. Both commands
+use masked prompts.
+
+Authenticate a connector provider:
+
+```sh
+openwiki auth slack
+openwiki auth gmail
+openwiki auth x
+openwiki auth notion
+```
+
+Start an ngrok tunnel for Slack OAuth:
+
+```sh
+openwiki ngrok start
+```
+
+This starts ngrok with a random HTTPS forwarding URL. OpenWiki reads ngrok's
+local inspection API, appends `/callback`, and saves
+`OPENWIKI_HTTPS_OAUTH_REDIRECT_URI` automatically. Register the printed callback
+URL in Slack. If you have a fixed ngrok domain, run
+`openwiki ngrok start https://<your-ngrok-domain>`. X/Twitter and Gmail auth
+ignore that HTTPS override and keep using the local loopback callback,
+`http://127.0.0.1:53682/callback`.
+
+`openwiki` creates initial repository documentation in `openwiki/` when no wiki exists. Source ingestion runs and scheduled connector updates maintain the local general-purpose wiki in `~/.openwiki/wiki/`. By default, the CLI stays open after each run so you can send follow-up messages. Use `-p` or `--print` for a one-shot non-interactive run that prints the final assistant output.
+
+Use `openwiki personal --init` for the local personal brain wiki or `openwiki code --init` for repository documentation. Bare `openwiki --init` is no longer supported because init needs an explicit mode. `openwiki --update` defaults to personal mode unless you pass `code`, `personal`, or `--mode`.
+
+On each `code` run, `openwiki` maintains both an `AGENTS.md` and a `CLAUDE.md` at the repository root, adding prompting that instructs your coding agent to reference the wiki when searching for context. Each file is created if it does not already exist. If a file is present, OpenWiki only rewrites its own `<!-- OPENWIKI:START -->…<!-- OPENWIKI:END -->` block and leaves the rest of your content untouched (appending the block the first time). The scheduled GitHub Actions workflow includes these files, along with the workflow itself, in the documentation pull request.
+
+On the first interactive run, OpenWiki will have you configure your inference provider, API key, and LLM. You will also be able to set a LangSmith API key to trace your OpenWiki runs to a LangSmith tracing project named "openwiki" (optional).
+
+These configuration options and secrets will be saved to `~/.openwiki/.env` on your local machine.
+
+To run in a container or use a different writable location, set
+`OPENWIKI_CONFIG_DIR` before starting OpenWiki. It relocates the local `.env`,
+personal wiki, connectors, and skills together; the default remains
+`~/.openwiki`.
+
+## Local Connectors
+
+OpenWiki's first-run onboarding offers connector setup for local Git repositories, Notion, Gmail, X/Twitter, Web Search, and Hacker News. During an ingestion run, deterministic connector tools write raw data and manifests under `~/.openwiki/connectors/<connector>/raw/`, then source-specific agent runs synthesize the local wiki under `~/.openwiki/wiki/` from those local files.
+
+You can configure the same connector more than once. For example, add one Web
+Search source for AI research and another for NBA news; OpenWiki stores them as
+separate source instances such as `web-search-1` and `web-search-2`. Run all
+instances with `openwiki ingest all`, all instances for one connector with
+`openwiki ingest web-search`, or one instance with
+`openwiki ingest web-search-2`.
 
 - `git-repo` reads configured local repository paths and writes compact manifests.
 - `x` uses the X API directly with OAuth user-context credentials for home timeline, user posts, mentions, bookmarks, and list posts.

src/agent/index.ts

@@ -32,7 +32,9 @@ import {
 } from "../diagnostics.js";
 import {
   openWikiConversationHistoryDir,
+  openWikiHomeDisplayPath,
   openWikiLocalWikiDir,
+  openWikiLocalWikiDisplayPath,
   openWikiSkillsDir,
 } from "../openwiki-home.js";
 import { resolveLanguage } from "../language.js";
@@ -159,7 +161,7 @@ export async function runOpenWikiAgent(
 
   await loadOpenWikiEnv();
   await syncBundledSkills();
-  emitDebug(options, "env=loaded ~/.openwiki/.env");
+  emitDebug(options, `env=loaded ${openWikiHomeDisplayPath}/.env`);
   emitDebug(options, `env.afterLoad ${formatEnvironmentDebug()}`);
 
   const openWikiIgnore =

src/agent/prompts/code.ts

@@ -1,12 +1,17 @@
+import {
+  openWikiConnectorsDisplayPath,
+  openWikiHomeDisplayPath,
+  openWikiLocalWikiDisplayPath,
+} from "../../openwiki-home.js";
 export const CODE_SYSTEM_PROMPTS = {
   chat: `You are OpenWiki, an expert technical writer, software architect, and product analyst.
 
 Your job is to inspect the relevant evidence, then produce documentation in the target repository's openwiki/ directory that is excellent for both humans and future agents.{OUTPUT_LANGUAGE_INSTRUCTIONS}
 
 Canonical wiki location:
 - The generated OpenWiki knowledge base lives in the target repository's openwiki/ directory, which the filesystem tools expose under the virtual path /openwiki. Reference wiki files by /-rooted virtual paths such as /openwiki/quickstart.md and /openwiki/architecture/overview.md.
-- In repository runs the wiki is this repo-local /openwiki directory, not ~/.openwiki/wiki.
-- Never type ~, ~/.openwiki/wiki, or host paths like /Users/... into filesystem tools (ls, read_file, write_file, edit_file, glob, grep).
+- In repository runs the wiki is this repo-local /openwiki directory, not ${openWikiLocalWikiDisplayPath}.
+- Never type ~, ${openWikiLocalWikiDisplayPath}, or host paths like /Users/... into filesystem tools (ls, read_file, write_file, edit_file, glob, grep).
 
 Use only the tools available to you. Prefer built-in filesystem discovery tools such as ls, glob, grep, read_file, write_file, and edit_file for targeted reads. {GIT_HISTORY_HINT}Do not invent files, modules, APIs, business rules, or behavior. Ground every important claim in source files, tests, existing docs, or git evidence you have inspected.
 
@@ -41,10 +46,10 @@ OpenWiki CLI reference:
 - \`openwiki personal\` opens the interactive local personal brain chat.
 - \`openwiki --init [message]\` initializes repository documentation under openwiki/ (code mode).
 - \`openwiki --update [message]\` updates repository documentation under openwiki/ (code mode).
-- \`openwiki personal --init [message]\` initializes the local personal brain wiki under ~/.openwiki/wiki.
+- \`openwiki personal --init [message]\` initializes the local personal brain wiki under ${openWikiLocalWikiDisplayPath}.
 - \`openwiki code --init [message]\` initializes repository documentation under openwiki/.
 - \`openwiki --mode code --init [message]\` initializes repository documentation under openwiki/.
-- \`openwiki --mode personal --init [message]\` initializes the local personal brain wiki under ~/.openwiki/wiki.
+- \`openwiki --mode personal --init [message]\` initializes the local personal brain wiki under ${openWikiLocalWikiDisplayPath}.
 - \`openwiki -p "message"\` or \`openwiki --print "message"\` runs once, prints the final assistant output, and exits.
 - \`openwiki --modelId <id>\` selects a model ID for that run.
 - \`openwiki --help\` prints current usage, options, and examples.
@@ -114,7 +119,7 @@ Initialize a source-grounded code wiki under /openwiki in the root of the reposi
 Hard constraints:
 - Filesystem / is the repository root. Read repository source as evidence, but write generated files only under /openwiki. Do not modify source code, /AGENTS.md, /CLAUDE.md, or /openwiki/INSTRUCTIONS.md.
 - Read /openwiki/INSTRUCTIONS.md when present; it is the user-authored scope and priority brief, not generated documentation.
-- Never pass ~, ~/.openwiki/wiki, or host paths such as /Users/... to filesystem tools. Shell commands run from the repository runtime root. Do not search parent or unrelated directories.
+- Never pass ~, ${openWikiLocalWikiDisplayPath}, or host paths such as /Users/... to filesystem tools. Shell commands run from the repository runtime root. Do not search parent or unrelated directories.
 - Do not read or document secrets, credentials, tokens, private keys, or .env files. Read sample environment files only when they contain placeholders.
 - Directory index.md files are generated after the run. Do not create or edit index.md files.
 - Use targeted ls, glob, grep, rather than broad root scans or full reads of large files.