@docyrus/docyrus 0.0.43 → 0.0.44

package/README.md

@@ -25,26 +25,6 @@ or
 pnpm add -g @docyrus/docyrus
 ```
 
-## Environments
-
-List and switch environments:
-
-```bash
-docyrus env list
-docyrus env use live
-```
-
-Default environments:
-
-- `live` -> `https://api.docyrus.com`
-- `beta` -> `https://beta-api.docyrus.com`
-- `alpha` -> `https://alpha-api.docyrus.com`
-- `dev` -> `https://localhost:3366`
-
-Aliases:
-
-- `prod` -> `live`
-
 ## Authentication
 
 Login with explicit client ID:
@@ -61,6 +41,15 @@ Logout active account:
 docyrus auth logout
 ```
 
+Work with accounts and tenants:
+
+```bash
+docyrus auth accounts list --json
+docyrus auth accounts use --userId "<user-id>" --json
+docyrus auth tenants list --userId "<user-id>" --json
+docyrus auth tenants use "<tenant-id-uuid-or-tenant-no>" --userId "<user-id>" --json
+```
+
 ## Help
 
 ```bash
@@ -70,63 +59,25 @@ docyrus env --help
 docyrus auth --help
 docyrus discover --help
 docyrus knowledge --help
+docyrus project-plan --help
 docyrus ds --help
 docyrus apps --help
 docyrus studio --help
+docyrus connect --help
 docyrus agent --help
 docyrus coder --help
+docyrus server --help
 docyrus tui --help
 ```
 
-## Example Usages
-
-Get current environment and active user/tenant context:
-
-```bash
-docyrus --json
-```
-
-Switch environment:
-
-```bash
-docyrus env use beta
-docyrus env list --json
-```
-
-Login and inspect current identity:
-
-```bash
-docyrus auth login --clientId "83a8df32-3738-4b5a-a0c7-87976adb1631"
-docyrus auth who --json
-```
-
-List apps:
-
-```bash
-docyrus apps list --json
-```
-
-Download current tenant OpenAPI spec:
-
-```bash
-docyrus discover api --json
-```
-
-Discover from downloaded tenant OpenAPI spec:
-
-```bash
-docyrus discover namespaces --json
-docyrus discover path /v1/users --json
-docyrus discover endpoint /v1/users/me --json
-docyrus discover endpoint [PUT]/v1/users/me/photo --json
-docyrus discover entity UserEntity --json
-docyrus discover search users,UserEntity --json
-```
+## Knowledge Graph
 
 Initialize and use the repo knowledge graph:
 
 ```bash
 docyrus knowledge init
+docyrus knowledge generate-initial
+docyrus knowledge refresh
 docyrus knowledge locate "Working Agreement" --json
 docyrus knowledge section "knowledge#Working Agreement" --json
 docyrus knowledge refs "knowledge#Working Agreement" --json
@@ -136,15 +87,42 @@ docyrus knowledge check --json
 docyrus knowledge config --json
 ```
 
-Work with accounts and tenants:
+## Project Plan
+
+The project plan is a repo-tracked work graph stored at `docyrus/project-plan/project-plan.json`. It organizes work into sections (standalone groupings like phases or feature areas), features, and tasks. A derived `PROJECT_PLAN.md` is always kept in sync. Features are also synced into the knowledge base features document when it exists.
+
+Manage sections, features, and tasks:
 
 ```bash
-docyrus auth accounts list --json
-docyrus auth accounts use --userId "<user-id>" --json
-docyrus auth tenants list --userId "<user-id>" --json
-docyrus auth tenants use "<tenant-id-uuid-or-tenant-no>" --userId "<user-id>" --json
+docyrus project-plan show --json
+docyrus project-plan check --json
+docyrus project-plan ensure --json
+
+# Sections
+docyrus project-plan upsert-section --title "Core Features" --json
+docyrus project-plan upsert-section --title "Testing" --slug "testing" --summary "Test coverage" --json
+
+# Features
+docyrus project-plan upsert-feature --sectionId "<section-id>" --title "Auth Flow" --json
+docyrus project-plan upsert-feature --sectionId "<section-id>" --title "Data Export" --slug "data-export" --summary "CSV and JSON export" --json
+
+# Tasks
+docyrus project-plan upsert-task --featureId "<feature-id>" --title "Implement OAuth2" --type new-implementation --assignee agent --json
+docyrus project-plan upsert-task --featureId "<feature-id>" --title "Fix token refresh" --type bug-fix --assignee agent --status in_progress --json
+docyrus project-plan get-task --taskId "<task-id>" --json
+docyrus project-plan set-task-status --taskId "<task-id>" --status done --json
+
+# Linked local subtasks
+docyrus project-plan create-linked-todo --taskId "<task-id>" --json
+docyrus project-plan create-linked-todo --taskId "<task-id>" --title "Step 1" --body "Details" --json
 ```
 
+Task types: `new-implementation`, `bug-fix`, `api-test`, `browser-automation-test`, `work`
+Assignees: `agent`, `user`
+Statuses: `planned`, `in_progress`, `blocked`, `done`
+
+## Data Sources
+
 Query data source items:
 
 ```bash
@@ -175,11 +153,44 @@ docyrus ds create base task --from-file ./tasks.csv --json
 docyrus ds update base task --from-file ./tasks-update.json --json
 ```
 
-Call raw API endpoints via curl command:
+## OpenAPI Discovery
+
+Download current tenant OpenAPI spec:
 
 ```bash
-docyrus curl /users/me -i --json
-docyrus curl /dev/apps --json
+docyrus discover api --json
+```
+
+Discover from downloaded tenant OpenAPI spec:
+
+```bash
+docyrus discover namespaces --json
+docyrus discover path /v1/users --json
+docyrus discover endpoint /v1/users/me --json
+docyrus discover endpoint [PUT]/v1/users/me/photo --json
+docyrus discover entity UserEntity --json
+docyrus discover search users,UserEntity --json
+```
+
+## Connectors
+
+```bash
+docyrus connect list-connectors --json
+docyrus connect get-connector <slug> --json
+docyrus connect get-action <slug> <actionKey> --json
+docyrus connect list-connections <slug> --json
+docyrus connect curl <slug> <endpoint> --json
+docyrus connect run-action <appSlug> <actionKey> --json
+```
+
+## Apps and Studio
+
+List and manage apps:
+
+```bash
+docyrus apps list --json
+docyrus apps delete --appId "<app-id>" --json
+docyrus apps restore --appId "<app-id>" --json
 ```
 
 Manage dev studio data sources, fields, and enums:
@@ -205,12 +216,23 @@ docyrus studio update-enums --appId "<app-id>" --dataSourceId "<data-source-id>"
 docyrus studio delete-enums --appId "<app-id>" --dataSourceId "<data-source-id>" --fieldId "<field-id>" --data '["enum-1","enum-2"]' --json
 ```
 
+## Raw API Access
+
+```bash
+docyrus curl /users/me -i --json
+docyrus curl /dev/apps --json
+```
+
+## TUI
+
 Launch the OpenTUI terminal UI (requires Bun):
 
 ```bash
 docyrus tui
 ```
 
+## Agent Server
+
 Start the agent HTTP server:
 
 ```bash
@@ -222,6 +244,8 @@ docyrus server --model anthropic/claude-sonnet-4-20250514 --thinking high
 
 For full endpoint documentation see [docs/API.md](docs/API.md).
 
+## Pi Agent and Coding Agent
+
 Launch the scoped pi assistant and coding agent:
 
 ```bash
@@ -239,6 +263,8 @@ docyrus agent --print "Which tenant am I using?"
 docyrus coder --print --mode json "Summarize the CLI command surface in this repo"
 ```
 
+### Built-in Agent Tools
+
 When `docyrus/knowledge/` exists, `docyrus agent`, `docyrus coder`, and `docyrus server` load built-in knowledge tools:
 
 - `docyrus_knowledge_search`
@@ -248,26 +274,33 @@ When `docyrus/knowledge/` exists, `docyrus agent`, `docyrus coder`, and `docyrus
 - `docyrus_knowledge_expand`
 - `docyrus_knowledge_check`
 
-When `docyrus/project-plan/project-plan.json` exists, `docyrus agent`, `docyrus coder`, and `docyrus server` also load:
+When `docyrus/project-plan/project-plan.json` exists, the `project_task` tool is also loaded with actions: `show`, `get`, `create-section`, `create-feature`, `create-task`, `set-status`, `create-linked-todo`.
+
+The `todo` tool is always available with actions: `list`, `list-all`, `get`, `create`, `update`, `append`, `delete`, `claim`, `release`.
 
-- `project_task`
+### Slash Commands
 
 Inside the interactive agent TUI:
 
 ```bash
-/login   # browser or API-key provider chooser
-/logout  # remove saved provider configuration
-/plan [task]  # start a planning-only branch and keep the current plan in .docyrus/plans/
-/end-plan  # leave the planning branch, summarize it, and return to the original branch
-/end-architect  # alias for leaving an architect planning session
-/plan-policy  # show the effective planning-model policy and the resolved planning model
-/architect [brief]  # discover tenant data sources and generate local planning artifacts under ./docyrus/architecture/
-/tasks  # browse the canonical project-plan sections, features, and tasks
+/login            # browser or API-key provider chooser
+/logout           # remove saved provider configuration
+/plan [task]      # start a planning-only branch and keep the current plan in .docyrus/plans/
+/end-plan         # leave the planning branch, summarize it, and return to the original branch
+/architect [brief] # discover tenant data sources and generate planning artifacts under ./docyrus/architecture/
+/end-architect    # alias for leaving an architect planning session
+/plan-policy      # show the effective planning-model policy and the resolved planning model
+/read-only        # enter read-only mode — write and edit tools are disabled
+/end-read-only    # exit read-only mode and resume normal operation
+/tasks            # browse the canonical project-plan sections, features, and tasks
+/todos            # interactive todo manager
 ```
 
 When running through `docyrus server`, `/plan` and `/architect` can be sent through `/api/chat` as normal chat input. If clarification is needed, the server emits a synthetic `ask_user` client tool. Frontends using AI SDK `useChat` should render that tool and submit structured answers back with `addToolOutput`.
 
-Optional planning-model policy:
+### Planning-Model Policy
+
+Optional planning-model policy for controlling which model is used during `/plan` sessions:
 
 - Project config: `<project>/.pi/plan-policy.json`
 - Global config: `~/.pi/agent/plan-policy.json`