{
  "markdown": "# Knowledge Base Wiki Agent\n\nA reusable FastAPI service for creating, adapting, maintaining, and querying\nGit-backed Wiki.js knowledge bases. The application repository contains only agent\ncode, reusable templates, tests, and deployment configuration; knowledge content\nlives in target Git repositories.\n\n## What it does\n\n- Creates a new knowledge-base structure from user-defined sections.\n- Adapts an existing Git repository into the accepted structure.\n- Adds a manifest, `AGENTS.md`, generated `index.md`, and append-only `log.md`.\n- Adds Wiki.js frontmatter to existing Markdown while preserving valid metadata.\n- Routes misplaced Markdown into configured sections.\n- Extracts and converts PDF, DOCX, and HTML documents into Markdown pages.\n- Accepts later document ingestion into any initialized knowledge repository.\n- Presents a complete Git diff before any commit or push.\n- Pulls again at approval time and stops on conflicting upstream changes.\n- Answers questions through lightweight Markdown search and verified source links.\n\n## Target repository contract\n\nEvery managed repository contains `.knowledgebase.yml`:\n\n```yaml\nversion: 1\ntitle: Engineering Knowledge\ndescription: Shared engineering guides and decisions.\nwiki_url: https://wiki.example.com\nsections:\n  - key: guides\n    title: Guides\n    description: Reusable procedures and operating guides.\n    scoped: false\n  - key: projects\n    title: Projects\n    description: Project-specific decisions and implementation notes.\n    scoped: true\nagent_page: AGENTS.md\nindex_page: index.md\nlog_page: log.md\nextra_root_markdown: []\nsupport_directories:\n  - assets\nsupport_files:\n  - .gitattributes\n  - .gitignore\n```\n\nNormal sections store pages directly, such as `guides/deployment.md`. Scoped\nsections require a named subfolder, such as\n`projects/project-atlas/material-pipeline.md`. Section keys and scope folders are\nlowercase URL-safe slugs.\n\nThe manifest lets each wiki use its own subject area and information architecture.\n\n## Installation\n\nRequirements:\n\n- [uv](https://docs.astral.sh/uv/)\n- Git\n- A corporate OpenAI-compatible chat-completions endpoint\n- Git credentials with read and push access to target repositories\n\n```powershell\nuv sync --extra dev\nCopy-Item .env.example .env\n```\n\nConfigure `.env`:\n\n| Variable | Purpose |\n| --- | --- |\n| `KB_DATA_DIR` | Uploads, JSON job state, patches, reader caches, and temporary clones |\n| `KB_GIT_AUTHOR_NAME` | Author used for approved commits |\n| `KB_GIT_AUTHOR_EMAIL` | Email used for approved commits |\n| `KB_WIKI_URL` | Base URL used when returning Wiki.js source links |\n| `OPENAI_BASE_URL` | Corporate OpenAI-compatible `/v1` endpoint |\n| `OPENAI_API_KEY` | Corporate API credential |\n| `OPENAI_MODEL` | Deployed chat model |\n| `KB_ALLOWED_ORIGINS` | Comma-separated Wiki.js origins allowed by CORS |\n| `KB_MAX_UPLOAD_MB` | Maximum size of each uploaded document |\n\nKeep `KB_DATA_DIR` outside both this application repository and all managed\nknowledge repositories in production. Do not put credentials in repository URLs;\nuse the host Git credential helper, SSH agent, or CI credentials.\n\nRun the service:\n\n```powershell\nuv run uvicorn kb_agent.main:app --host 0.0.0.0 --port 8000 --reload\n```\n\nAPI documentation is available at `/api/docs`.\n\n## Create a knowledge repository\n\nThe remote may be empty. Supply the desired structure to\n`POST /api/repositories`:\n\n```json\n{\n  \"repository\": \"git@gitlab.example.com:knowledge/engineering.git\",\n  \"branch\": \"main\",\n  \"title\": \"Engineering Knowledge\",\n  \"description\": \"Shared engineering guides and decisions.\",\n  \"wiki_url\": \"https://wiki.example.com\",\n  \"adapt_existing\": false,\n  \"sections\": [\n    {\n      \"key\": \"guides\",\n      \"title\": \"Guides\",\n      \"description\": \"Reusable procedures and operating guides.\",\n      \"scoped\": false\n    },\n    {\n      \"key\": \"projects\",\n      \"title\": \"Projects\",\n      \"description\": \"Project-specific decisions and notes.\",\n      \"scoped\": true\n    }\n  ]\n}\n```\n\nThe background job creates the manifest, root templates, and section directories,\nthen returns a reviewable diff. Poll `GET /api/jobs/{id}` and approve with:\n\n```json\n{\"approved\": true}\n```\n\nApproval is sent to `POST /api/jobs/{id}/approve`.\n\n## Adapt an existing knowledge repository\n\nUse the same request with `adapt_existing: true`. The adapter:\n\n1. clones the requested branch;\n2. preserves already valid pages;\n3. adds Wiki.js frontmatter to unformatted Markdown;\n4. routes documents into the closest configured section;\n5. parses PDF, DOCX, and HTML files into Markdown;\n6. preserves non-document directories and files as declared support paths;\n7. creates missing root templates and the manifest;\n8. validates links and paths, then returns the complete diff.\n\nIf a document belongs to a scoped section and the scope is unknown, the job enters\n`needs_input`. Resume through the approval endpoint:\n\n```json\n{\n  \"approved\": true,\n  \"scopes\": {\n    \"projects\": \"Project Atlas\"\n  }\n}\n```\n\nNo changes are committed until the resulting diff is explicitly approved.\n\n## Ingest documents into any initialized repository\n\n`POST /api/ingest` accepts Markdown, PDF, DOCX, and HTML multipart uploads:\n\n```powershell\ncurl.exe -X POST http://localhost:8000/api/ingest `\n  -F \"repository=git@gitlab.example.com:knowledge/engineering.git\" `\n  -F \"branch=main\" `\n  -F 'scopes={\"projects\":\"Project Atlas\"}' `\n  -F \"files=@architecture-decision.docx\" `\n  -F \"instructions=Keep the rollout and rollback procedures.\"\n```\n\nThe corporate model receives the target manifest, `AGENTS.md`, generated index,\nrelated page excerpts, supplied scopes, and extracted source content. It may update\nmultiple established pages or create new ones, but it can only use configured\nsections and supplied scope names.\n\n## Chat and source access\n\nChat requests identify the target repository:\n\n```json\n{\n  \"repository\": \"git@gitlab.example.com:knowledge/engineering.git\",\n  \"branch\": \"main\",\n  \"message\": \"How do we roll back the service?\",\n  \"max_sources\": 6\n}\n```\n\n`POST /api/chat` returns sanitized Markdown as server-sent events followed by\nverified sources. Retrieve an individual page with:\n\n```text\nGET /api/source/guides/deployment?repository=REPOSITORY&branch=main\n```\n\n## Wiki.js widget\n\n```html\n<script\n  src=\"https://agent.example.com/widget/chat-widget.js\"\n  data-api-url=\"https://agent.example.com\"\n  data-wiki-url=\"https://wiki.example.com\"\n  data-repository=\"git@gitlab.example.com:knowledge/engineering.git\"\n  data-branch=\"main\"\n  data-title=\"Knowledge Assistant\">\n</script>\n```\n\nThe widget renders sanitized Markdown in an isolated shadow root and opens verified\nsources in Wiki.js.\n\n## Maintenance CLI\n\nValidate or update any initialized checkout:\n\n```powershell\nuv run kb-maintain --repo C:\\knowledge\\engineering\nuv run kb-maintain --repo C:\\knowledge\\engineering --check\n```\n\nMaintenance validates the repository-specific manifest, Wiki.js frontmatter,\nsection paths, scoped folders, duplicate routes, and internal links. It rebuilds\n`index.md` in manifest order and appends unrecorded non-bot commits to `log.md`.\nCheck mode restores generated files before exiting.\n\n## Verification\n\n```powershell\nuv run pytest\nuv run ruff check .\nnode --check widget/chat-widget.js\n```\n",
  "bytes": 7234,
  "sha": "e827ef24dbe5bb6a122d44b18a8f692df86d779b2faf3b90e9ae8464279d7be0",
  "repo_slug": "josephkirk/wiki_agent",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_josephkirk_wiki_agent_kb_agent_template__2fdb1b9a/readme"
}