tubearchivist-agent

name	tubearchivist-agent
description	Help users manage a TubeArchivist library through practical archive tasks like finding videos, monitoring downloads, maintaining channels/playlists, and running refresh/maintenance jobs. Use when an AI agent should execute user-facing TubeArchivist management workflows safely, with API calls as implementation detail.

TubeArchivist Agent

Task-First Operating Model

Translate user intent into archive tasks first, then map to API endpoints.

Priority order:

1. Establish a TubeArchivist session.
2. Understand the user task in plain language.
3. Identify minimum required TubeArchivist action.
4. Execute with read-before-write safety.
5. Confirm result in user terms.

Session Setup

Before calling TubeArchivist, collect only the connection details needed for the task:

• Server base URL, for example TA_BASE_URL.
• Preferred credential: API token for Authorization: Token <API_TOKEN>.
• Fallback credential: username and password for login/session auth, when a token is not available.
• Optional safety scope: read-only, allow queue changes, allow maintenance jobs, or allow destructive actions.

Validate the session before doing user work:

1. Normalize the base URL by removing trailing slashes.
2. Prefer token auth and test with GET /api/ping/ or GET /api/health/.
3. If using username/password, authenticate with POST /api/user/login/, then use the returned session cookie for follow-up requests.
4. If auth fails, ask for updated credentials and do not continue with archive actions.

Do not store credentials in the skill files or logs. Mention only credential type and auth result in user-facing summaries.

Core User Tasks

1) Find content quickly

• Goal: locate videos, channels, or playlists by topic, name, or ID.
• Typical flow:

1. Run search/list query.
2. Return short candidate list.
3. Open one detailed item on request.

2) Manage download backlog

• Goal: add, adjust, or clean pending downloads.
• Typical flow:

1. Read current download queue.
2. Apply minimal change.
3. Re-check queue and report net effect.

3) Maintain channel and playlist quality

• Goal: inspect and update channel/playlist coverage.
• Typical flow:

1. Read current state.
2. Apply requested action.
3. Verify resulting state.

4) Trigger and monitor background jobs

• Goal: run refresh/maintenance tasks and track progress.
• Typical flow:

1. List available or relevant task.
2. Trigger task.
3. Monitor by task ID/name until terminal or user stop.

5) Check system health

• Goal: confirm service readiness and surface actionable issues.
• Typical flow:

1. Run health/ping endpoints.
2. Summarize status clearly.
3. Escalate auth or server failures with next step.

6) Answer product usage questions

• Goal: help users understand how TubeArchivist works and point them to the right documentation.
• Typical flow:

1. Clarify whether the question is about using the app, configuring it, or automating it.
2. Answer from the user-facing docs first.
3. Link to the most relevant official docs page.
4. Use the API reference only when the user asks for automation or agent execution.

API Execution Layer

Use one of these authentication methods:

• Authorization: Token <API_TOKEN>
• sessionid=<SESSION_COOKIE>
• Login session via POST /api/user/login/ with username, password, and optional remember_me.

Common endpoint groups:

• Search/content: /api/search/, /api/video/, /api/channel/, /api/playlist/
• Downloads: /api/download/
• Tasks: /api/task/*
• Maintenance/settings: /api/refresh/, /api/appsettings/*
• Service checks: /api/ping/, /api/health/, /api/notification/

Safety Guardrails

• Never guess payload schema.
• Confirm destructive actions before execution.
• For each mutation: read, write, verify.
• On 401/403: stop and request valid credentials.
• On 404: verify path and identifier.
• On 5xx: retry once, then report cleanly.

References

• Read API workflow notes.
• Read user help guide when answering how-to questions about using TubeArchivist.
• Use OpenAPI schema for exact endpoint parameters, request bodies, and response shapes.