KeyTub - How to Use
===================

KeyTub is a secure desktop application for organising useful information
in a searchable SQLite database. It can store items such as usernames,
passwords, software settings, licence details, server information, account
references, and general notes.


1. First Start
==============

1. Open KeyTub.
2. On a new database, select SET NEW PASSWORD.
3. Enter and confirm a password containing at least 8 characters.
4. Store that password somewhere safe. KeyTub cannot recover it if it is
   forgotten.
5. After the database unlocks, the padlock turns green and the Keys and
   Values tab opens.

On later starts, select UNLOCK and enter the same password.


2. Understanding an Entry
=========================

Each row stores one named piece of information.

Entity
------
The broad subject or owner of the information. Examples:

- Personal
- Work
- My Company
- A customer or supplier name
- Home Network
- Laptop

Main Category
-------------
A required first grouping within the Entity. Examples:

- Websites
- Email
- Microsoft 365
- Accounting Software
- Servers
- Router

Sub Category and Sub Category 2
-------------------------------
Optional extra levels for organising larger collections. Examples:

- Entity: Work
- Main Category: Websites
- Sub Category: Banking
- Sub Category 2: Current Account

Key
---
The name or label of the item. Examples:

- Username
- Password
- Website
- Licence Key
- Installation Path
- SMTP Server
- Port

Key is an editable dropdown. Existing keys are suggested when the selected
Entity and Main Category match earlier entries. You can always type a new
key.

Value
-----
The information belonging to the Key. Value supports multiple lines.

Notes
-----
Optional supporting information, reminders, URLs, or instructions.

Status
------
A simple way to identify the state of an entry:

- Active
- InActive
- Review
- Check
- New
- In Progress
- Complete

The Entity, Main Category, Key, and Value fields are required.
Sub Category, Sub Category 2, and Notes are optional.


3. Adding Data
==============

1. Unlock the database.
2. Open the Keys and Values tab.
3. Enter an Entity.
4. Enter Main Category.
5. Add Sub Category and Sub Category 2 if they help organise the entry.
6. Enter a Key.
7. Enter the Value.
8. Add optional Notes and select a Status.
9. Select NEW.

After an entry is created, Key, Value, and Notes are cleared. The category
fields remain ready for the next related item.


4. Notes and Events
===================

Use the Notes and Events tab for dated notes, reminders, tasks, and events.

- Date / Time is recorded automatically when the entry is created.
- Main Category and Event / Note are required.
- Sub Category and Deadline are optional.
- Status is optional. When used, it can be Not Complete, In Progress,
  Complete, or Cancelled.
- Not Complete deadlines are orange when due today and red when overdue.
- Status cells use red for Not Complete, yellow for In Progress, and green
  for Complete.
- Filters are available for categories, status, deadline state, and text.

NEW, COPY, UPDATE, DELETE, and CLEAR work in the same way as on the Keys
and Values tab. Notes and Events has its own CSV import, visible export,
and complete export using its seven-column format.


5. Example Uses
===============

Website Login
-------------

Store a username and password as two separate rows with the same category
path:

Row 1:
- Entity: Personal
- Main Category: Websites
- Sub Category: Shopping
- Sub Category 2: Example Shop
- Key: Username
- Value: your email address or username
- Notes: website address

Row 2:
- Use the same Entity and category fields
- Key: Password
- Value: the account password
- Notes: optional recovery information

Program Settings
----------------

Use one row for each setting:

- Entity: Work Laptop
- Main Category: Programs
- Sub Category: Backup Software
- Key: Backup Folder
- Value: the folder used by the program

Other useful keys might include Configuration File, Server Address,
Database Name, Update Channel, or Installation Path.

Software Licence
----------------

- Entity: Work
- Main Category: Software Licences
- Sub Category: Program Name
- Key: Licence Key
- Value: the licence or activation code
- Notes: purchase date, renewal date, or supplier

Server or Network Details
-------------------------

Create separate rows for Hostname, IP Address, Port, Username, Password,
and Connection Method:

- Entity: Customer Name
- Main Category: Servers
- Sub Category: Production
- Sub Category 2: Web Server
- Key: IP Address
- Value: the server address

Email Settings
--------------

Use separate rows for Email Address, Username, Password, IMAP Server,
SMTP Server, and Port:

- Entity: Personal
- Main Category: Email
- Sub Category: Account Name
- Key: SMTP Server
- Value: the outgoing mail server

Reference Information
---------------------

KeyTub can also hold non-secret information such as account numbers,
support contacts, serial numbers, renewal dates, useful commands, and
setup notes.


6. Selecting and Changing Entries
=================================

Select a row in the data grid to load it into the Data Entry section.

UPDATE
------
Change the fields and select UPDATE. The Updated date is changed
automatically.

COPY
----
Select a row and choose COPY to create a new duplicate. The new row is
selected so it can be adjusted. This is useful for related settings that
share the same categories.

DELETE
------
Select a row and choose DELETE. Confirm the warning to permanently remove
the entry.


7. Finding Data
===============

The filters above the grid update the visible rows:

- Entity filters the broad subject.
- Main Category is populated from the selected Entity.
- Status filters by the selected status.
- Text Search looks in Main Category, Sub Category, Sub Category 2, Key,
  Value, and Notes.
- CLEAR FILTERS removes all current filters.

The row count below the grid shows how many rows are currently visible.
The normal ordering is Entity, Main Category, Sub Category,
Sub Category 2, Key, and Value.


8. Importing and Exporting Data
===============================

- Select EXPORT VISIBLE to save the rows currently shown in the grid.
  Apply filters first if only part of the database should be exported.
- Select EXPORT ALL DATA to save every database record, regardless of the
  current filters. The confirmation states how many records will be saved.
- Select IMPORT DATA to add records from a CSV created by an export on the
  same tab. KeyTub validates the complete file before making changes.
  When duplicates are found, skipping them is the default choice.
- Imports into an empty database preserve the original record IDs. Imports
  into a database that already contains records assign new IDs. Created and
  Updated dates are preserved in both cases.

Important: CSV exports contain readable, decrypted information. Store,
send, and dispose of exported files carefully. A CSV is not an encrypted
database backup. Values masked in the grid are included in readable form so
that an exported file can be imported without losing data.


9. Locking and Passwords
========================

- Select LOCK on the Welcome screen or Security > Lock when leaving the
  computer.
- Select UNLOCK on the Welcome screen or Security > Unlock Password to
  regain access.
- Use Security > Change Password to re-encrypt the complete SQLCipher
  database with a new password.
- The minimum password length is 8 characters. A longer, unique password
  is recommended.

The complete SQLCipher database is encrypted on disk, including categories,
statuses, dates, notes, events, schema, indexes, journal, and WAL content.
Data is readable in application memory while KeyTub is unlocked.


10. Database Tasks
=================

Backup Database
---------------

Use File > Backup Database before important changes and on a regular
schedule. Choose a safe destination, preferably with another secure copy
on separate storage. After a backup completes successfully, the Welcome
screen and status footer show the date and time under Last Backup.

Restore Database
----------------

Use File > Restore Database to replace the active database with a valid
KeyTub backup. KeyTub validates the selected database and creates a safety
backup of the current database before restoring it. The password belonging
to the restored database will be required.

Name Database
-------------

Use File > Name Database to set the friendly name shown on the Welcome
screen and footer. You can optionally rename the physical .db file. The
file remains in the KeyTub application data folder.

Reset Database
--------------

File > Reset Database permanently removes all entries and password
settings and creates a new database. This cannot be undone. Create a
backup first if the existing data might be needed.

Database Location and Health
----------------------------

The database status tooltip in the footer displays the active location.
KeyTub uses the normal per-user application data folder for the operating
system rather than the program folder.

The footer shows the database name, lock state, and health. A bright green
dot and OK indicate that the periodic database check succeeded.


11. Good Practice
=================

- Use a strong, unique database password and keep it in a safe place.
- Lock KeyTub whenever the computer is unattended.
- Make regular database backups and test that they can be located.
- Protect backups because they contain the complete encrypted database.
- Protect CSV exports even more carefully because their contents are
  readable.
- Use consistent Entity and category names to keep suggestions and
  filters useful.
- Store one item per row. For example, store Username and Password as
  separate rows under the same category path.
- Use Notes for context, not as a replacement for a clear Key.


Frequently Asked Questions
==========================

What happens if I enter the wrong password?
--------------------------------------------
KeyTub checks the password and reports that it is incorrect. The database
remains locked.

Can KeyTub recover a forgotten password?
-----------------------------------------
No. The password is not stored in readable form, and encrypted entries
cannot be recovered without the correct password.

Which fields are encrypted?
---------------------------
All database fields are encrypted at rest by SQLCipher. The database file
cannot be read by standard SQLite without the correct password.

Why can I not open or use the Keys and Values tab?
--------------------------------------------------
The database must first be unlocked from the Welcome screen or Security
menu.

Can I type a value that is not in a dropdown?
----------------------------------------------
Yes. The category, filter, and Key dropdowns allow typing. Their lists are
suggestions based on existing data.

Why are no Key suggestions displayed?
--------------------------------------
Key suggestions use existing rows that match both the current Entity and
Main Category. Select or enter those fields first.

What is the difference between a database backup and a CSV export?
------------------------------------------------------------------
A database backup is a copy of the encrypted KeyTub database and includes
its password configuration and metadata. A CSV export contains readable
records and can transfer those records through IMPORT DATA, but it is not a
complete replacement for a database backup.

Where is my database stored?
----------------------------
The exact path is shown in the database status tooltip in the footer. On
Windows it is normally under the current user's local application data
folder. On Linux it is normally under the current user's local share folder.

Does changing the database name remove or re-encrypt data?
-----------------------------------------------------------
No. It changes the friendly name and, if selected, the filename. Existing
entries and encryption remain unchanged.

Does changing the password update existing entries?
----------------------------------------------------
Yes. SQLCipher rekeys the complete database using the new password.

What does Reset Database do?
----------------------------
It deletes the active data and password configuration and creates a new,
empty database. The action cannot be undone.

Why is the row count lower than the total number of entries?
-------------------------------------------------------------
One or more filters are active. Select CLEAR FILTERS to show all rows.

Can I use KeyTub on Linux?
--------------------------
The Python application supports Windows and Ubuntu/Kubuntu. Installation
and desktop shortcut instructions are included in the requirements.txt
file supplied with the application.

Where can I see application changes?
------------------------------------
Open Help > Changes to view the change log.
