docs/BLACK_DRAGON_COMPLETE_GUIDE.md

# Black Dragon AI - Complete Guide

Last updated: 21 May 2026

## What It Is

Black Dragon AI is a local-first AI assistant created for Sir Roky. It runs as a Python backend plus a browser frontend. The frontend has no API-key input and does not contain the AI API key. The backend must be running for Black Dragon to work.

Local app link:

```text
http://127.0.0.1:8787/
```

## Start On This PC

Double-click:

```text
start-backend.bat
```

Or run:

```powershell
cd "C:\Users\HP\Documents\Codex\2026-05-17\doctype-html-html-lang-en-head"
python backend\server.py
```

Then open:

```text
http://127.0.0.1:8787/
```

For Chrome app mode, double-click:

```text
BlackDragon-Chrome-App.bat
```

## Backend API Key

The AI API key is stored only in:

```text
backend_data/secrets.json
```

Do not paste the key into `index.html`, Android files, public hosting, screenshots, or shared messages. The backend can also read `GROQ_API_KEY` from the environment if you prefer environment secrets later.

## Terms First

The browser app and Android APK require Terms and Privacy Policy acceptance before chat, memory, notes, PC commands, or antivirus scan actions run. The current accepted Terms version is:

```text
2026-05-21-v3
```

## Data Storage

Backend database:

```text
backend_data/black_dragon.db
```

Temporary chat mirror logs:

```text
%TEMP%\BlackDragonChats\
```

Notes are saved in the backend database. Typed notes and mouse/finger drawings are both supported.

## Main Features

- Backend-only AI chat with fallback knowledge lookup.
- Long-term memory manager with explicit memory commands, a Memory panel, duplicate prevention, and simple automatic personal-fact memory.
- Memory commands: `remember that ...`, `what do you remember`, `forget memory`.
- Creator lock: questions about who made Black Dragon answer `Sir Roky made me.`
- Name lock: questions about the assistant name answer `My name is Black Dragon.`
- Safe PC assistant for status, disk, process, network, allowlisted app opening, and scans.
- Microsoft Defender scan integration with suspicious-file fallback.
- Voice input, voice output, and live talk mode.
- Air Canvas for 2D drawing to animated 3D preview.
- Notes mode for typed and drawn notes.
- Gaming Zone with Flap Dragon, Dragon Race, Space Shooter, Feed Dragon, and more.
- File/image attachment flow.
- Scan-before-accept file upload flow for text, image, and binary files.
- Browser image lookup from third-party browser-accessible sources.
- Prompt-injection firewall, PII masking, route selection, hash logs, RAG-style document ingestion, queue, SDK samples, and analytics endpoints.

## Safety Rules

Black Dragon is not given unlimited destructive PC control. It blocks high-risk commands such as formatting disks, deleting Windows/system folders, disabling firewall/security, shutdown/restart, and destructive registry or disk operations. Add new PC actions only through allowlisted backend code.

Antivirus features depend on Microsoft Defender or the fallback suspicious-file scan. They are helpful checks, not a guarantee that every threat will be found.

## Image Disclaimer

Image results may come from browser-accessible sources, search engines, Wikimedia-style APIs, or third-party websites. Black Dragon does not own, license, verify, or guarantee those images. Users must check copyright, trademark, privacy, consent, licensing, and usage rights before copying, sharing, editing, publishing, or commercial use.

## Terms, Privacy, And License

Read these before sharing:

```text
docs/TERMS_AND_CONDITIONS.md
docs/PRIVACY_POLICY.md
LICENSE
```

The Terms and Privacy Policy are practical templates, not legal advice. No terms document can honestly guarantee that nobody can ever file a legal claim. Before public release or commercial use in India, ask a qualified Indian lawyer to review the final operator name, contact details, grievance process, jurisdiction, consent flow, age rules, retention period, and data deletion process.

Official references used while preparing the templates:

- Digital Personal Data Protection Act, 2023: https://www.indiacode.nic.in/indiacode/handle/123456789/22037?view_type=browse
- IT Intermediary Rules, 2021: https://meity.gov.in/writereaddata/files/IT%20Intermediary%20Rules%2C%202021%20updated%20on%2028.10.2022.pdf
- MeitY FAQ on IT Rules, 2021: https://www.meity.gov.in/writereaddata/files/FAQ_Intermediary_Rules_2021.pdf

## Hosted Website And APK

For a phone APK that does not need your phone connected to your PC, deploy the backend to a public HTTPS server. The same URL is the website:

```text
https://your-black-dragon-server.example.com/
```

Deployment files:

```text
Dockerfile
deploy/env.example
deploy/render.yaml
deploy/PUBLIC_HOSTING.md
```

The Android project is in:

```text
android-apk\
```

The APK wrapper opens a backend URL in a WebView. The API key is not inside the APK. The APK also shows its own Terms acceptance screen before opening Black Dragon, then syncs the accepted Terms version into the web app.

Before building the final hosted APK, set this in `MainActivity.java`:

```java
private static final String DEFAULT_BACKEND_URL = "https://your-black-dragon-server.example.com/";
```

Local hotspot testing is still possible:

```text
start-backend-lan.bat
http://192.168.137.1:8787/
```

Build command after Android tools are installed:

```powershell
cd android-apk
gradle assembleDebug
```

Expected APK output:

```text
android-apk\app\build\outputs\apk\debug\app-debug.apk
```

This workspace also copies the latest debug APK to:

```text
C:\Users\HP\Desktop\BlackDragon-debug.apk
```

The debug APK is for testing and direct installation. For store/public production release, create a private release keystore and build a signed release APK/AAB.

## Production Checklist

- Use HTTPS for any public deployment.
- Add login/authentication before exposing PC assistant endpoints.
- Move secrets to environment variables or a managed secret store.
- Add rate limits and audit log retention rules.
- Add user consent, privacy notice, deletion, and grievance workflows.
- Review Terms and Privacy Policy with a lawyer.
- Do not expose the local backend publicly unless PC-control endpoints are protected.
- Keep Windows, Python, browsers, and Microsoft Defender updated.