# Introduction An introduction to Principal Plan. ## Overview Principal Plan is a desktop personal finance application built around envelope budgeting. Instead of only reviewing spending after the fact, you assign income to virtual envelopes as it arrives, giving every dollar a job before you spend it. The application runs entirely on your computer. Your data is stored locally in a single file, and there is no cloud account to create. Your financial data never leaves your machine. Principal Plan is available for Windows (via the Microsoft Store) and macOS (via the Mac App Store). ## Main Window The main window has three main areas: a left panel, a central workspace, and a menu bar along the top. ### Left Panel The left panel contains three sections, shown either as tabs or stacked vertically: - **Accounts** -- A tree view showing your financial accounts. Each account displays its current balance and cleared balance. Accounts can be organized into groups and reordered by dragging. - **Envelopes** -- A tree view showing your spending categories. Each envelope displays its current balance. Envelopes can be nested inside other envelopes for hierarchical organization. - **Templates** -- A list of reusable transaction blueprints. Templates capture recurring patterns like monthly bills or regular income and feed into the [Allocation Plan](Allocation_Plan.html). ### Central Content Area The central workspace uses tabs. Double-click an account or envelope in the left panel to open a ledger tab for that item's transactions. You can keep multiple ledgers open while moving between accounts and envelopes. Each ledger tab includes a filter toolbar for narrowing the displayed transactions by date, clearing status, or custom criteria. ### Menu Bar The menu bar contains three menus: **File** -- File operations and application settings: - **New** -- Create a new Principal Plan file. - **Open** -- Open an existing file. - **Save** / **Save As** -- Save the current file. - **Revert** -- Revert the file to the state it was in when first opened this session. - **Import** -- Import transactions from CSV, OFX/QFX, or QIF files. - **Create Checkpoint** / **Restore Checkpoint** -- Save and restore named snapshots of your data. - **Settings** -- Open the settings dialog. **View** -- Open ledger views and the budgeting tool: - **Account Ledger** -- Open a ledger tab for a selected account. - **Envelope Ledger** -- Open a ledger tab for a selected envelope. - **Allocation Plan** -- Open the budget allocation dialog. **Help** -- Help, registration, and licensing: - **Help Contents** -- Open the help website. - **Website** -- Open the Principal Plan website. - **License** -- Check your license status or purchase a license. - **Registration** -- Open the registration and telemetry dialog. - **About Principal Plan** -- View version information. ## Key Features ### Envelope Budgeting The core workflow is simple: income arrives, you distribute it across envelopes, and spending draws from those envelopes. This encourages a plan-before-you-spend habit. Envelopes also support spending limits and watchdog alerts for low balances. ### Allocation Plan The [Allocation Plan](Allocation_Plan.html) is a forward-looking budget view. It uses your templates to project expected income and expenses, then shows how each deposit should be divided across your envelopes. You can view the plan by day, week, month, or year. ### Importing Principal Plan imports transaction data from bank downloads in CSV, OFX/QFX, and QIF formats. The import system includes automatic transaction matching to avoid duplicates, payee and memo filtering, and a file watch feature that can monitor a download path and trigger an import automatically. ### Search and Replace The [Search and Replace](Search_Replace.html) tool operates on the visible transactions in the current ledger. It can search in payee, memo, and code fields with options for case sensitivity and exact matching. ### Reports Three report dialogs provide financial summaries: - [Account Activity Report](Account_Activity_Report.html) -- Current and cleared balances for selected accounts as of a chosen date. - [Envelope Summary Report](Envelope_Summary_Report.html) -- Envelope balances with allocation plan integration. - [Envelope Activity Report](Envelope_Activity_Report.html) -- Allocation, expenses, and transfers per envelope over a date range. Each report supports printing, print preview, copy to clipboard, and CSV export. ### Printing Print preview renders account and envelope ledgers before they are sent to the printer. Ledger and report dialogs can print, preview, export, or copy their output where those options are available. ### Backup and Recovery Automatic backups are created once per session when you save a changed file. If you open a file and close it without making changes, no backup is created. The backup depth setting controls how many backup copies are retained. Checkpoints provide named snapshots you can restore at any time. An archive feature moves historical data to a separate file to keep your working file lean. ## Account Types Principal Plan supports twenty account types: | Type | Description | |---|---| | **Checking** | A standard checking account. | | **Savings** | A savings account. | | **Credit Card** | A credit card account. The balance represents the amount owed. | | **Cash** | Physical cash on hand. | | **E-Cash** | Electronic cash accounts such as PayPal or Venmo. | | **Investment** | General investment accounts. | | **Group** | An organizational container that holds other accounts. Groups do not have their own transactions. | | **Loan** | A personal or auto loan. | | **Mortgage** | A home mortgage. | | **Retirement** | Retirement accounts such as 401(k) or IRA. | | **Brokerage** | A brokerage or trading account. | | **HSA** | A Health Savings Account. | | **Crypto** | Cryptocurrency wallets and exchanges. | | **Prepaid** | Prepaid debit cards. | | **Money Market** | A money market account. | | **CD** | A certificate of deposit. | | **Business** | A business or commercial account. | | **Property** | Real estate or other property assets. | | **Insurance** | Insurance policies with a cash value. | | **Gift Card** | Gift cards and store credit. | ## Transaction Types The transaction editor exposes four transaction types: | Type | Description | |---|---| | **Simple** | A single deposit or payment in one account assigned to one envelope. | | **Transfer** | Moves money between accounts, between envelopes, or both. | | **Regular Multiple** | Splits one deposit or payment across multiple envelope allocations. With **Enable Account Transfers in Multiples** enabled, it can also transfer part of the amount to another account. | | **Multiple Envelope Transfer** | Moves budget amounts among multiple envelopes in one transaction. | Each transaction carries a date, amount, payee, memo, check code, and clearing status (none, pending, or cleared). ## Languages Principal Plan is available in six languages: English, German, Spanish, French, Italian, and Portuguese. The language can be changed in the [Settings](Settings.html) dialog. ## Getting Started When you launch Principal Plan for the first time, the [Start Wizard](Start_Wizard.html) walks you through creating your initial accounts, setting up income templates, and building a basic allocation plan. # Start Wizard Create your first Principal Plan file. ![Start Wizard](images/Start_Wizard.png) ## Overview The **Start Wizard** appears automatically when you launch Principal Plan for the first time or create a new file. It walks through three setup steps: creating accounts, defining income templates, and building an initial allocation plan (budget). The wizard is modal. You must either complete it or click **Quit Wizard** to dismiss it. Every page includes a **Help** button that opens this help topic. ## Welcome Page The first page is an introduction. It explains the three steps the wizard will walk you through: 1. Create accounts. 2. Create templates for income sources. 3. Create a simple allocation plan (budget). Click **Next** to continue. ## Accounts Page The accounts page asks you to create at least one account record. Click **Add Account** to open the [Account Properties](Account_Properties.html) dialog where you enter the account name and type. You can add as many accounts as you like by clicking **Add Account** again. After you finish the wizard, open each account ledger and enter an opening transaction if you need to set an opening balance. That opening transaction should usually match the ending balance on your most recent bank statement. You can adjust account properties and balances later, so an estimate is enough to start. At least one account is required. If you try to advance without adding an account, a warning appears and you must go back and add one. Click **Next** to continue. ## Income Page The income page asks you to create income templates. Templates are reusable transaction blueprints. In this step you define your regular income sources so the allocation plan knows how much money is available to budget. Click **Add Income** to open the [New Allocation Plan Template](New_Allocation_Plan_Template.html) dialog. For each income source, enter a name (for example, "Paycheck"), a frequency (such as once every month), and an amount. The template is automatically included in the allocation plan. You can add multiple income templates by clicking **Add Income** again. This step is optional -- you can skip it and add income templates later. Click **Next** to continue. The wizard creates a default set of envelopes and opens the [Allocation Plan](Allocation_Plan.html) dialog so you can review and customize the budget before finishing. ## Default Envelopes When the wizard advances past the income page, it creates eleven starter envelopes with default budget percentages: | Envelope | Percentage | |---|---| | Charity | 10% | | Food | 9% | | Housing | 25% | | Insurance | 8% | | Medical | 8% | | Miscellaneous | 5% | | Personal | 5% | | Recreation | 5% | | Savings | 10% | | Transportation | 8% | | Utilities | 7% | Each envelope's allocation amount is calculated as its percentage of the total income defined by your templates. These envelopes and their allocations can be renamed, reorganized, or deleted after the wizard finishes. ## Allocation Plan Review After the default envelopes are created, the [Allocation Plan](Allocation_Plan.html) dialog opens automatically. This shows how each income deposit will be divided across your envelopes. You can adjust amounts, add envelopes, or remove envelopes here. When you close the allocation plan dialog, the wizard advances to the final page. ## Final Page The final page confirms that setup is complete. The **Quit Wizard** button is hidden on this page because there is nothing left to cancel. Click **Finish** to close the wizard and start using Principal Plan. ## Quitting the Wizard If you click **Quit Wizard** on any page before the final page, the wizard closes and creates a minimal default setup: - If no accounts were added, a single account named "New Account" is created. - If no envelopes were added, the eleven default envelopes listed above are created. This ensures the application always has at least one account and a set of envelopes, even if you skip the wizard entirely. # Registration Stay in touch and share anonymous usage data. ![Registration](images/Registration.png) ## Overview The **Registration** dialog optionally records your contact information and controls anonymous usage data sharing. Both options are completely voluntary and are off by default. The dialog appears once automatically after the [Start Wizard](Start_Wizard.html) completes on first launch. You can reopen it at any time from **Help** > **Registration**. ## Dialog Controls The dialog contains a checkable **Keep me informed** contact group and a separate **Share anonymous usage data** checkbox. ### Keep me informed The **Keep me informed** group enables contact registration. When checked, the contact fields within the group become active: - **Email** -- Your email address. - **First Name** -- Your first name. - **Last Name** -- Your last name. At least one name (first or last) and a valid email address are required. The **OK** button is disabled until these requirements are met. When unchecked, the contact fields are grayed out and no registration data is sent. When you click **OK** with this option checked, your contact information is sent to the Principal Plan registration server. If you reopen the dialog later and click **OK** again, the registration is re-sent with your current information, allowing you to update your name or email. ### Share anonymous usage data The **Share anonymous usage data** checkbox enables anonymous telemetry. When checked, Principal Plan periodically sends basic usage statistics including the application version, platform, session count, and language setting. Telemetry does not begin immediately. When you first enable this option, a random delay of 7 to 30 days is set before the first transmission. This delay is applied only once; if you later disable and re-enable telemetry, it resumes without a new delay. ### OK and Help Click **OK** to save your choices and close the dialog. Click **Help** to open this help topic. ## Privacy Principal Plan uses two separate, unrelated identifiers to keep contact data and usage data completely independent: - **Contact identifier** -- Generated when the application is first installed. Sent only with registration data (your name and email). Never included in telemetry. - **Telemetry identifier** -- A separate, anonymous identifier also generated on first install. Sent only with usage statistics. Never associated with your contact information. Because these identifiers are independent, there is no way to link your anonymous usage data to your contact registration, even if you opt into both. ### What is sent | | Registration | Telemetry | |---|---|---| | Name and email | Yes | No | | Application version | Yes | Yes | | Platform | Yes | Yes | | Session count | No | Yes | | Language | No | Yes | | Personal identifier | Contact ID | Anonymous ID | ### What is not sent No financial data, file contents, transaction details, account names, envelope names, or balances are ever transmitted. The application stores all financial data locally and does not communicate it to any server. # License Purchase or upgrade your Principal Plan license. ![License](images/License.png) ## Overview The **License** dialog shows your current license status and provides purchase and upgrade options. Open it from **Help** > **License...**. ## License Options The dialog presents three purchase options: - **Monthly** -- A recurring monthly subscription. - **Annual** -- A recurring annual subscription. - **Forever** -- A one-time purchase that never expires. Each button displays its price as retrieved from the Microsoft Store (Windows) or App Store (macOS). If prices cannot be loaded (for example, when offline), the buttons show a placeholder. Clicking a purchase button launches the store purchase flow. When the purchase completes, the dialog updates to show your active license. ## Upgrading If you already hold a license, the dialog shows which tier is active. You can upgrade or switch tiers: - **Monthly held** -- The **Monthly** button is disabled. You can switch to **Annual** or upgrade to **Forever**. - **Annual held** -- The **Annual** button is disabled. You can switch to **Monthly** or upgrade to **Forever**. - **Forever held** -- All purchase buttons are disabled. There is nothing further to purchase. ## Offline Behavior License verification normally requires a connection to the store. If the store is unreachable, Principal Plan uses the file's saved license and trial state to decide access. Files previously saved while licensed continue to open with full access. Files that are still within their trial period continue to open with trial access. If the file is not licensed and the trial has expired, the file is closed and a new file is created until the license can be verified or a license is purchased. # Envelope Budgeting The budgeting philosophy behind Principal Plan. ## Overview Envelope budgeting assigns every dollar of income to a job as soon as it arrives. The name comes from the old practice of dividing cash into physical envelopes labeled with spending categories -- groceries, rent, entertainment, and so on. When an envelope is empty, spending in that category stops until new income refills it. Principal Plan implements this model digitally. You create virtual envelopes for spending and saving categories, then assign each non-transfer account transaction to the appropriate envelope or envelopes. Deposits and payments update the account view and the envelope view at the same time. ## How It Works The envelope budgeting cycle in Principal Plan follows two steps: ### 1. Income Arrives and Is Allocated When you receive income -- a paycheck, a refund, or any other deposit -- it enters one of your accounts and is assigned to one or more envelopes in the same transaction. The [Allocation Plan](Allocation_Plan.html) helps you decide how much of each deposit should go to each envelope based on the frequency and amount of your expected bills and savings goals. For example, if your rent is $1,200 per month and you are paid twice a month, the plan might allocate $600 from each paycheck to your "Rent" envelope. ### 2. Spend from Envelopes When you spend money, the transaction draws from both an account (where the money physically leaves) and an envelope (the category that funded the purchase). The account balance and the envelope balance decrease at the same time. If an envelope runs low, the watchdog system can alert you before you overspend. Each envelope can have a spending limit that triggers a **Watchdog Alert** when the balance drops below it. ## Why Envelope Budgeting Traditional budgeting often looks backward: you review what you spent last month and try to adjust. Envelope budgeting looks forward: you decide where money goes before you spend it. This shift from reactive to proactive budgeting has several benefits: - **No surprise shortfalls.** Bills are funded before discretionary spending happens. - **Built-in spending limits.** Each envelope acts as a natural cap on its category. - **Clear trade-offs.** Moving money from one envelope to another makes the cost of a decision visible. - **Debt reduction.** By allocating money to debt payment envelopes first, you ensure consistent payments regardless of other spending. ## Envelopes and Accounts Principal Plan tracks every transaction from two angles simultaneously: the account it affects and the envelope it draws from. Accounts represent where your money physically lives (a bank, a wallet, a credit card). Envelopes represent what your money is for (rent, groceries, savings). See the [Principal Plan's Envelope Model](PPlan_Envelope_Model.html) and [Accounts vs. Envelopes](Accounts_vs_Envelopes.html) topics for more detail on how this dual tracking works. ## Templates and the Allocation Plan Templates capture your recurring financial patterns -- a monthly rent payment, a biweekly paycheck, a quarterly insurance bill. Each template records the amount, frequency, account, and envelope for a transaction that happens on a regular schedule. The [Allocation Plan](Allocation_Plan.html) uses your templates to build a forward-looking budget view. It shows how each income deposit should be divided across your envelopes, normalized to a common time frame (daily, weekly, monthly, or yearly). This is the core planning tool that makes envelope budgeting work at scale. ## Getting Started If you are new to envelope budgeting, start with a small structure: 1. Create a few broad envelopes -- housing, food, transportation, savings. 2. Set up income templates for your regular deposits. 3. Use the [Allocation Plan](Allocation_Plan.html) to decide how income should be divided across envelopes. 4. As the system becomes familiar, split broad envelopes into more specific ones. The [Start Wizard](Start_Wizard.html) walks you through this process when you first launch Principal Plan. # Principal Plan's Envelope Model How Principal Plan tracks money across accounts and envelopes simultaneously. ## Overview Principal Plan tracks every dollar from two angles. Accounts show where money physically lives -- which bank, wallet, or credit card. Envelopes show what the money is for -- the budget category assigned to each dollar. Every transaction is recorded in both systems at the same time, and the two must always agree. This dual-tracking model lets envelope budgeting work alongside traditional account management. ## Dual Balances Every account and every envelope maintains two running balances: | Balance | Description | |---|---| | **Balance** | The total of all transactions assigned to this account or envelope. | | **Cleared** | The total of transactions that have been marked as cleared. This typically matches what the bank reports. | The **Balance** column updates as transactions are created, edited, or deleted. The **Cleared** column updates as transactions are cleared during reconciliation. ## Every Transaction Touches Both Sides When you enter a transaction -- say a $50 grocery purchase -- you assign it to both an account (your checking account, where the $50 leaves) and an envelope (your groceries envelope, where the $50 is budgeted). The checking account balance and the groceries envelope balance both decrease by $50. The result is: - The sum of all account balances always equals the sum of all envelope balances. - You can answer "how much money do I have at First National?" (account view) and "how much have I budgeted for groceries?" (envelope view) from the same data. ## Independent Clearing Each transaction carries two independent clearing states -- one for the account side and one for the envelope side. A transaction can be cleared in your account (your bank confirms it) without being cleared in your envelope, and vice versa. This independence lets you reconcile your bank statement without affecting your envelope bookkeeping. ## Integrity Principal Plan checks balance integrity every time a file is opened: 1. The total account balance must equal the total envelope balance. 2. Both stored balances must match a fresh calculation from all transaction records. 3. Every transaction must have both a valid account and a valid envelope assignment. If any check fails, the file is reported as corrupt. These checks keep the dual-tracking model consistent, so money cannot appear in one view without being accounted for in the other. ## Transfers Transfers move money between accounts without affecting envelopes. When you transfer $500 from checking to savings, the checking balance decreases and the savings balance increases, but no envelope balance changes. The money was already allocated to its envelopes -- moving it between accounts does not change its purpose. Envelope transfers work the other way: they move money between envelopes without affecting accounts. This lets you reallocate your budget without moving money between banks. ## Hierarchy Both accounts and envelopes support hierarchical organization. Accounts can be grouped into account groups (for example, grouping all retirement accounts together). Envelopes can be nested inside other envelopes (for example, a "Housing" parent with "Rent" and "Utilities" children). Parent nodes show the combined balance of all their descendants. # Accounts vs. Envelopes Understanding the difference between accounts and envelopes. ## Overview Accounts and envelopes are the two fundamental organizing structures in Principal Plan. They track different aspects of the same money. Understanding the difference makes the rest of the application easier to use. **Accounts** represent where your money physically lives -- a checking account, a credit card, or cash in your wallet. **Envelopes** represent what your money is for -- rent, groceries, savings, or entertainment. Most day-to-day transactions appear in both views. Transfers can appear only in the account view or only in the envelope view, depending on whether you are moving money between real financial accounts or reallocating money between budget categories. ## Key Differences | | Accounts | Envelopes | |---|---|---| | **Represents** | A real-world financial container (bank, wallet, card) | A virtual budget category (purpose, goal) | | **Types** | 20 types: **Checking**, **Savings**, **Credit Card**, **Cash**, **E-Cash**, **Investment**, **Group**, **Loan**, **Mortgage**, **Retirement**, **Brokerage**, **HSA**, **Crypto**, **Prepaid**, **Money Market**, **CD**, **Business**, **Property**, **Insurance**, **Gift Card** | No types -- envelopes are generic categories shaped by name and purpose | | **Watchdog** | No | Yes -- alerts when the balance drops below a limit | | **Allocation Plan** | No | Yes -- envelopes can be flagged for inclusion | | **Web Address** | Yes -- links to the institution's website | No | | **Opening Balance** | Entered as an account transaction after creating the account | No | | **Balance Display** | Always shown | Configurable per envelope | | **Grouping** | Account groups (a special type) | Nested parent/child envelopes | ## When to Use Each Create an **account** for each place where you hold money: - Your checking account - Your savings account - Each credit card - Cash on hand - Investment or retirement accounts Create an **envelope** for each purpose you budget for: - Fixed expenses: rent, utilities, insurance - Variable expenses: groceries, dining, transportation - Savings goals: emergency fund, vacation, new car - Debt payments: credit card payoff, loan payments ## How They Work Together When income arrives as a deposit into your checking account, the account balance goes up. You then allocate that income across your envelopes using the [Allocation Plan](Allocation_Plan.html), which raises the envelope balances. When you spend, the transaction reduces both the account balance (money left the bank) and the envelope balance (budget for that category was used). The money is gone from both views at the same time. When you transfer between accounts (checking to savings), no envelope is affected -- the money still has the same purpose. When you transfer between envelopes (moving budget from dining to groceries), no account is affected -- the money still lives in the same bank. ## Balance Equality Principal Plan keeps the account view and envelope view in balance. Day-to-day deposits and spending usually change both views, while account transfers and envelope transfers move money within one view without changing the total. The balance of each view is always the same. # Using Credit Cards How credit cards work within the envelope budgeting model. ## Overview Credit cards can be confusing in envelope budgeting because the purchase and the bill payment happen at different times. Principal Plan handles this by debiting the envelope when you spend. Paying the credit card bill is an account transfer and does not touch any envelope. ## Setting Up a Credit Card Create a new account and set its type to **Credit Card**. The account balance represents the amount you owe. A new credit card with no charges starts at zero; as you make purchases, the balance goes negative (reflecting debt). ## Making a Purchase A credit card purchase is recorded the same way as any other transaction. You enter the date, payee, and amount, then assign it to the credit card account and the appropriate envelope. For example, buying $40 of groceries on your credit card: - The credit card account balance decreases by $40 (you now owe $40 more). - The groceries envelope balance decreases by $40 (you spent $40 of your grocery budget). The key point: **the envelope is debited at the time of purchase, not at the time of payment.** Your budget changes as soon as you make the purchase. ## Paying the Bill When you pay your credit card bill, you record an account transfer from your checking account to the credit card account. For example, paying $500 toward the card: - The checking account balance decreases by $500. - The credit card account balance increases by $500 (you now owe $500 less). - No envelope balance changes. No envelope is affected because the money was already budgeted and deducted when each purchase was entered. The payment only moves money between accounts. ## Why This Works This approach keeps both views accurate: - **Envelope balances** reflect how much budget remains in each category, regardless of which account was used to pay. A $40 grocery charge reduces the grocery envelope whether you used cash, debit, or credit. - **Account balances** reflect your actual position with each financial institution. The credit card account shows what you owe; checking shows what you have on hand. ## Reconciling a Credit Card Reconciling a credit card works the same as any other account. When your credit card statement arrives, open the credit card's account ledger, view pending transactions, and mark each one as cleared as it appears on the statement. The cleared balance should match the statement balance. ## Common Mistakes - **Do not wait until the bill arrives to enter purchases.** Enter each transaction when it happens so your envelope balances stay current. - **Do not debit an envelope when paying the bill.** The bill payment is just an account transfer. Debiting an envelope would double-count the expense. - **Do not use a "Credit Card Payment" envelope.** The payment moves money between accounts, not between budget categories. Creating a payment envelope leads to confusing balances. # Handling Debt Managing loans, mortgages, and other debt with envelope budgeting. ## Overview Principal Plan provides three account types for tracking debt: **Credit Card**, **Loan**, and **Mortgage**. All three work the same way: the account carries a negative balance that represents the amount you owe. Pair the debt account with a debt envelope so the account view and envelope view track the same obligation. For credit card spending, see the [Using Credit Cards](Using_Credit_Cards.html) topic. ## Setting Up Debt 1. Create a debt envelope, such as "Car Loan," "Mortgage," or "Student Loan." 2. Create a new account and choose **Loan**, **Mortgage**, or **Credit Card** as the type. 3. In the new account's ledger, enter an opening transaction for the current amount owed as a negative number (for example, -15,000 for a $15,000 car loan), and assign that transaction to the matching debt envelope. After setup, the debt account and debt envelope show the same negative balance. You can use one debt envelope for multiple debt accounts if you want to track them as a combined obligation. Because a debt envelope is intentionally negative, turn off its watchdog. ## Budgeting for Payments Allocate income to the debt envelope when you receive money. This sets money aside for the payment and decreases the negative balance in the envelope view. For example, allocating $400 to a "Car Loan" envelope changes the envelope balance from -15,000 to -14,600. The account balance remains -15,000 until you actually pay the lender. ## Paying the Bill When the bill is due, record an account transfer from your payment source (typically checking) to the debt account: - The checking account balance decreases by the payment amount. - The debt account balance increases (moves closer to zero). - The debt envelope balance does not change, because you already allocated the payment money to that envelope when the income arrived. After the transfer, the debt account and debt envelope match again. In the example above, both show -14,600 after the $400 payment is recorded. ## Recurring Payments with Templates Most debt payments happen on a regular schedule. You can create a transaction template for the payment transfer from checking to the debt account. Use the [Allocation Plan](Allocation_Plan.html) to allocate income to the debt envelope. Use a separate payment template to create the account transfer when the bill is due. ## Interest and Fees Interest charges and fees from the lender increase the debt. Record them as account transactions in the debt account. You can assign those transactions to the matching debt envelope too, so both views continue to match. Some users create a separate "Interest" envelope to track how much they are paying in interest over time. If you track interest separately, allocate income to that envelope as well so it remains funded. ## Tracking Progress Open the debt account's ledger to see payments and charges. Open the debt envelope's ledger to see the budget activity for the same obligation. As payments accumulate, both balances move toward zero. The **Envelope Activity** report can show how much you have allocated and spent on debt payments over any date range, helping you track progress against your payoff plan. ## Multiple Debts If you have multiple debts, consider organizing them in an account group. Create a **Group** account called "Debt" and drag your loan, mortgage, and credit card accounts into it. The group's balance shows your total debt at a glance. Similarly, you can nest debt envelopes under a parent "Debt Payments" envelope to see your total debt obligation in one place. # Transaction Workflow The lifecycle of a transaction from creation through clearing. ## Overview A transaction records a financial event in Principal Plan: a purchase, a deposit, a transfer, or a split. Each transaction moves from creation through optional clearing and reconciliation. ## Transaction Fields Each transaction carries the following information: | Field | Description | |---|---| | **Date** | The date the transaction occurred. | | **Payable To** | The payee or description of the transaction. | | **Amount** | The transaction amount, entered as either a **Payment** or **Deposit**. | | **Code** | An optional reference such as a check number. | | **Memo** | An optional note. | | **Account** | The account the transaction affects. | | **Envelope** | The envelope the transaction draws from or credits. | | **Cleared** | Two independent clearing states, one for the account and one for the envelope. | ## Transaction Types Principal Plan supports four transaction types: | Type | Description | |---|---| | **Simple** | A single deposit or payment in one account assigned to one envelope. | | **Transfer** | Moves money between accounts, between envelopes, or both. Use it when money changes location or budget category without creating new income or spending. | | **Regular Multiple** | Splits one deposit or payment across multiple envelope allocations. If **Enable Account Transfers in Multiples** is enabled, it can also move part of the amount to another account. | | **Multiple Envelope Transfer** | Moves budget amounts among multiple envelopes in one transaction. Use it to redistribute money across several envelope categories. | ## Creating a Transaction Open an account or envelope ledger by double-clicking an item in the left panel. In the ledger, use the **Add New Transaction** button or Ctrl+Insert to open the transaction editor. In the editor, use **Save & New** to save and start another transaction, or **Save & Close** to save and return to the ledger. The transaction editor includes fields for the transaction information listed above. Auto-complete is available for the **Payable To** and **Code** fields, drawing from your transaction history. When you select a payee from the auto-complete list, the other fields are filled in from the most recent matching transaction. Templates can also pre-fill a new transaction. Use **Create Transaction** from the right-click menu in the **Templates** list, or apply a template from within the transaction editor. ## Editing a Transaction Double-click a transaction in the ledger to open it for editing. All fields can be changed. If you change the amount on a transaction that has already been cleared, a warning appears and the clearing state is automatically reset on both the transaction and any related transfer or split records. ## Clearing States Each transaction has two independent clearing states -- one for the account side and one for the envelope side. The three states are: | State | Display | Description | |---|---|---| | Not Cleared | (blank) | The transaction has not been verified. | | Pending | * | The transaction has been marked by the user during reconciliation. | | Cleared | X | The transaction has been confirmed and saved. | Toggle a transaction between not cleared and pending by clicking the cleared column or selecting **Toggle Cleared** from the right-click menu. When a file is saved, pending transactions are promoted to cleared. ## Importing Transactions When transactions are imported from a bank download (CSV, OFX/QFX, or QIF), the import system attempts to match them against existing records. Matched transactions have their clearing state promoted to pending, confirming that the bank has processed them. Unmatched transactions are created as new records. Imported transactions can be identified using the **Filter View** option **Freshly Imported or Synchronized**. ## Deleting a Transaction Select a transaction in the ledger and delete it from the right-click menu. A confirmation dialog appears before the transaction is removed. Deleting a transfer or split transaction also removes its related records (the buddy or child items). # Reconciling an Account Verifying your records against bank statements. ## Overview Reconciling compares your Principal Plan records against a bank or credit card statement to confirm that both sides agree. Principal Plan provides a cleared balance, clearing toggles, and ledger filters that together serve as the reconciliation workflow. ## How It Works When your bank statement arrives (paper or online), follow these steps: 1. **Open the account ledger.** Double-click the account in the **Account List** to open its ledger tab. 2. **Filter to uncleared transactions.** Use the view menu or filter toolbar to show only pending items. The **View Pending** option shows all uncleared transactions. More specific filters like **View Pending Checks** and **View Pending Deposits** can help you work through the statement section by section. 3. **Mark each transaction.** As you find each transaction on the statement, click the cleared column or select **Toggle Cleared** from the right-click menu. The transaction changes from blank (not cleared) to a * (pending). 4. **Compare balances.** The ledger footer shows the running cleared balance. Compare this against the ending balance on your statement. When they match, reconciliation is complete. 5. **Investigate differences.** If the balances do not match, look for transactions that appear on the statement but not in your ledger (missed entries), or transactions in your ledger that the bank has not yet processed (outstanding items). ## Clearing States Each transaction carries two independent clearing states -- one for the account and one for the envelope. During account reconciliation, only the account-side clearing state changes. The envelope-side clearing state is independent and can be used for separate envelope reconciliation if desired. The three states are: | State | Indicator | Description | |---|---|---| | Not Cleared | (blank) | The transaction has not been verified against a statement. | | Pending | * | You have marked the transaction during the current reconciliation session. | | Cleared | X | The transaction has been confirmed and the file has been saved. | When you save the file, all pending transactions are promoted to cleared. Pending is only a working state for the current session, so you can see what you just marked separately from transactions cleared earlier. ## The Cleared Balance The cleared balance is the sum of all transactions that are not in the "not cleared" state. It appears in two places: - **The ledger footer** -- Shows the running cleared balance when the ledger is in cleared balance mode. - **The account list** -- The **Cleared** column shows the cleared balance for each account. The cleared balance corresponds to what your bank knows about. Transactions you have entered but the bank has not yet processed (outstanding checks, pending deposits) are excluded from the cleared balance but included in the full balance. ## Ledger Filters Several built-in filters help during reconciliation: | Filter | Description | |---|---| | **View Pending** | Shows all transactions that are not yet cleared. | | **View Pending Checks** | Shows uncleared transactions with a check code. | | **View Pending Deposits** | Shows uncleared deposit transactions. | | **View Pending Non-Checks** | Shows uncleared transactions that are not checks. | The custom filter dialog also provides a **Filter by Cleared State** option with choices for any state, cleared only, not cleared only, or not cleared and pending. ## Amount Changes and Clearing If you edit the amount of a transaction that has already been marked as pending or cleared, Principal Plan warns you and automatically resets the clearing state to not cleared. This also resets the clearing state on any related transfer or split records. This prevents the cleared balance from becoming inaccurate due to post-reconciliation edits. # Main Window Overview of the Principal Plan main window. ## Overview The main window is divided into two areas separated by a draggable splitter: a left panel containing the **Accounts**, **Envelopes**, and **Templates** lists, and a central content area that displays ledger tabs. ## Left Panel The left panel can operate in two modes, selectable in [Settings](Settings.html): - **Tab mode** -- The three lists appear as tabs. Click the **Accounts**, **Envelopes**, or **Templates** tab along the bottom to switch between them. - **Splitter mode** -- All three lists are stacked vertically. Drag the dividers between them to adjust how much space each list receives. Each list has its own toolbar with buttons for adding, deleting, and managing items. See the individual help topics for details: - **Account List** -- Managing your accounts. - **Envelope List** -- Managing your envelopes. - **Templates** -- Managing transaction templates. ## Central Content Area The central area uses a tabbed interface for viewing account and envelope ledgers. Tabs can be opened in several ways: - Double-click an account or envelope in the left panel. - Select **View** > **Account Ledger** or **View** > **Envelope Ledger** from the menu bar. - Use the keyboard shortcuts Ctrl+A (account ledger) or Ctrl+E (envelope ledger). Multiple tabs can be open at the same time. Tabs can be reordered by dragging and closed with the X button on each tab or by pressing Ctrl+W. ## Menu Bar The menu bar contains three menus: - **File** -- Create, open, save, import, and configure. - **View** -- Open ledger views and the **Allocation Plan**. - **Help** -- Access help, registration, licensing, and version information. See the Introduction topic for a full listing of menu items. ## Status Bar The status bar at the bottom of the window contains a text size slider on the right side. Drag the slider to adjust the font size used throughout the application. The change takes effect immediately and is saved between sessions. ## Window Title The window title shows the name of the currently open file followed by "Principal Plan" and the version number. ## Splitter The divider between the left panel and the central content area can be dragged to resize either side. The splitter position is saved and restored between sessions. # Account List The Accounts tab in the main window. ![Account List](images/Account_List.png) ## Overview The **Account List** is the first section of the left panel. It shows your financial accounts in a tree view, with groups acting as folders for other accounts. The list can show each account's current balance and cleared balance, depending on the configured columns. Double-click an account to open its ledger in a new tab. ## Columns The account list displays three columns: | Column | Description | |---|---| | **Account** | The account name and type icon. Group accounts display a folder icon. | | **Balance** | The current balance of the account, including all transactions. | | **Cleared** | The balance considering only cleared transactions. This matches what your bank reports. | Column widths can be adjusted by dragging the dividers in the header row. ## Toolbar The toolbar along the top of the account list provides quick access to common actions: | Button | Tooltip | Description | |---|---|---| | Add | **Add New Account** | Adds a new account or account group. Clicking the button shows a menu with **Insert Account** and **Insert Account Group** options. | | Delete | **Delete Selected Account** | Deletes the selected account. A confirmation dialog appears first. | | Import | **Import Transactions** | Opens the import dialog to bring in transactions from a CSV, OFX/QFX, or QIF file. | | Print | **Print Account List** | Prints the account list. | | Website | **Open Website for Selected Account** | Opens the web address associated with the selected account in your default browser. The web address is set in **Account Properties**. | | Settings | **Account List Settings** | Opens a settings dialog for the account list display options. | | Help | **Account List Help** | Opens this help topic. | ## Right-Click Menu Right-clicking in the account list opens a context menu with the following actions: - **Insert Account** -- Creates a new account under the selected group. - **Insert Account Group** -- Creates a new account group under the selected group. - **Delete** -- Deletes the selected account or accounts. - **Sort Ascending / Descending** -- Sorts accounts within the selected group by the column that was right-clicked. - **Open Website** -- Opens the web address for the selected account. - **Edit Properties** -- Opens the **Account Properties** dialog for the selected account. ## Organizing Accounts Accounts can be organized into groups. A group is a special account type that acts as a folder and does not have its own transactions. To create one, use the add button and select **Insert Account Group**. Drag accounts and groups to reorder them. You can drag an account into a group to nest it, or drag it out to move it to a different level. ## Selection The account list supports extended selection. Click to select a single account, hold Ctrl and click to add accounts to the selection, or hold Shift and click to select a range. The delete and properties actions work on the current selection. ## Editing Account Names Account names can be edited directly in the list by slowly double-clicking (click once to select, then click again on the name). Press Enter to confirm the new name or Escape to cancel. ## Deleting Accounts When deleting an account, a confirmation dialog warns that envelope balances associated with the account will be affected and spending history may be lost. The dialog suggests creating an account group for old, unused accounts rather than deleting them. You cannot delete the last account. At least one account must exist at all times. You also cannot delete an account group that still contains other items -- move or delete the contained items first. # Envelope List The Envelopes tab in the main window. ![Envelope List](images/Envelope_List.png) ## Overview The **Envelope List** is the second section of the left panel. It shows your spending categories as a tree of envelopes. Each envelope is a virtual container for part of your funds, supporting the envelope budgeting model where every dollar has a purpose before it is spent. Envelopes can be nested inside other envelopes for hierarchical organization. For example, a "Housing" envelope might contain child envelopes for "Rent," "Utilities," and "Insurance." Double-click an envelope to open its ledger in a new tab. ## Columns The envelope list displays four columns: | Column | Description | |---|---| | **Envelope** | The envelope name. Nested envelopes are indented under their parent. | | **!** | The watchdog indicator. Displays an alert icon when the envelope balance has fallen below its watchdog limit. | | **Balance** | The current balance of the envelope, including all transactions. Visibility is controlled per envelope in **Envelope Properties**. | | **Cleared** | The reconciled balance of the envelope. Visibility is controlled per envelope in **Envelope Properties**. | Column widths can be adjusted by dragging the dividers in the header row. ## Toolbar The toolbar along the top of the envelope list provides quick access to common actions: | Button | Tooltip | Description | |---|---|---| | Add | **Add New Envelope** | Creates a new envelope under the currently selected envelope. | | Delete | **Delete Selected Envelope** | Deletes the selected envelope. A confirmation dialog appears first. | | Zero Out | **Zero Out** | Transfers the remaining balance of the selected envelope to another envelope, bringing it to zero. | | Print | **Print Envelope Reports** | Opens a drop-down menu with two report options: **Envelope Activity** and **Envelope Summary**. | | Settings | **Envelope List Settings** | Opens a settings dialog for the envelope list display options. | | Help | **Envelope List Help** | Opens this help topic. | ## Right-Click Menu Right-clicking in the envelope list opens a context menu with the following actions: - **Insert Envelope** -- Creates a new envelope under the selected envelope. - **Delete Envelope** -- Deletes the selected envelope. - **Sort Ascending / Descending** -- Sorts envelopes within the selected parent by the column that was right-clicked. - **Zero Out** -- Transfers the remaining balance of the selected envelope to another envelope, bringing it to zero. - **Edit Properties** -- Opens the **Envelope Properties** dialog for the selected envelope. ## Watchdog Alerts The watchdog system monitors envelope balances and warns you when spending brings a balance below a threshold you define. Each envelope can have its own watchdog limit, set in **Envelope Properties**. When a transaction causes an envelope balance to drop below its limit, a **Watchdog Alert** dialog appears with the envelope name and new balance. The watchdog column in the list shows an alert icon for any envelope that is currently below its limit. Watchdog alerts can be disabled globally in [Settings — Messages](Settings_Messages.html). ## Zero Out The **Zero Out** action transfers the remaining balance of one or more selected envelopes to a destination envelope you choose. This is useful at the end of a budget period when you want to sweep leftover funds into a savings or rollover envelope. You cannot zero out an envelope against itself or against one of its own descendants. ## Envelope Properties Each envelope has the following configurable properties, accessible through **Edit Properties** in the right-click menu: - **Name** -- The display name of the envelope. - **Limit** -- The watchdog threshold amount. When the balance falls below this value, an alert is triggered. - **Watchdog On/Off** -- Enables or disables the watchdog for this envelope. When off, the limit field displays **Watchdog Off**. - **Display Envelope Balance in Envelope List** -- Controls whether the balance column shows a value for this envelope. - **Include this Envelope in the Allocation Plan** -- Marks the envelope for inclusion in the [Allocation Plan](Allocation_Plan.html). - **Display Envelope Reconcile Balance in Envelope List** -- Controls whether the cleared column shows a value for this envelope. - **Description** -- A free-text description of the envelope's purpose. ## Organizing Envelopes Drag envelopes to reorder them. You can drag an envelope into another envelope to nest it, or drag it out to change its position in the hierarchy. ## Deleting Envelopes When deleting an envelope that contains transactions or child envelopes, you must select a new envelope to receive the items being moved. You cannot move items into the envelope being deleted or into one of its descendants. You cannot delete the root envelope. # Templates The Templates tab in the main window. ![Templates](images/Templates.png) ## Overview The **Templates** section is the third section of the left panel. Templates are reusable transaction blueprints for recurring patterns such as monthly bills, regular income, or periodic transfers. They help you create transactions quickly and feed the [Allocation Plan](Allocation_Plan.html) so it can project future income and expenses. ## Columns The template list displays three columns: | Column | Description | |---|---| | **Template** | The template name. | | **In Plan** | Shows **Yes** or **No** to indicate whether the template is included in the [Allocation Plan](Allocation_Plan.html). | | **Amount** | The transaction amount defined in the template. | Column widths can be adjusted by dragging the dividers in the header row. The list can be sorted by any column using the right-click menu. ## Toolbar The toolbar along the top of the template list provides quick access to common actions: | Button | Tooltip | Description | |---|---|---| | Add | **Add New Template** | Creates a new template. The template editor opens with a blank **Simple** template. | | Delete | **Delete Selected Template** | Deletes the selected template after confirmation. | | Allocation Plan | **Allocation Plan** | Opens the **Allocation Plan** dialog, which uses in-plan templates to project your budget. | | Help | **Templates Help** | Opens this help topic. | ## Right-Click Menu Right-clicking a template in the list opens a context menu with the following actions: - **Edit Item** -- Opens the template editor to modify the selected template. - **Clone Item** -- Creates a duplicate of the selected template. The clone opens in the editor so you can adjust it before saving. - **Create Transaction** -- Creates a new transaction in the ledger using the template's values. The transaction editor opens with the template's fields pre-filled. ## Template Types Each template uses one of four types, selected from the **Type** drop-down in the template editor: | Type | Description | |---|---| | **Simple** | A single transaction in one account with one envelope. Covers basic deposits and payments. | | **Transfer** | A movement of money between two accounts, with corresponding envelope assignments. | | **Regular Multiple** | A deposit or payment split across multiple envelope allocations. If **Enable Account Transfers in Multiples** is enabled, rows can also transfer part of the amount to another account. | | **Multiple Envelope Transfer** | A transfer that splits across multiple envelope assignments. Used for redistributing funds among envelopes. | ## Frequency Every template has a frequency that defines how often the transaction occurs. The frequency controls are visible when the template is included in the [Allocation Plan](Allocation_Plan.html) and consist of three parts: - **Count** -- How many times the transaction occurs within the period (for example, "2" for a biweekly paycheck). - **Period** -- The number of time units between occurrences (for example, "1"). - **Span** -- The time unit: **Day**, **Week**, **Month**, or **Year**. Labels adjust to plural form (**Days**, **Weeks**, **Months**, **Years**) when the period is greater than one. For example, a template set to "1 time, every 1 Month" represents a monthly bill. A template set to "2 times, every 1 Month" represents something that occurs twice a month. The [Allocation Plan](Allocation_Plan.html) uses these frequencies to normalize all templates into a common time frame (daily, weekly, monthly, or yearly) and calculate projected balances. ## In Plan The **In Plan** flag controls whether the template is included in the [Allocation Plan](Allocation_Plan.html). When the flag is enabled, the template's frequency becomes relevant and the [Allocation Plan](Allocation_Plan.html) uses the template to project future income and expenses. Templates that are not in the plan can still create transactions manually. They do not appear in allocation projections. The flag can be toggled in the template editor via the **Include in Allocation Plan** checkbox. ## Template Editor The template editor (**Edit Transaction Template**) provides fields for all transaction details: - **Name** -- A unique name for the template. - **Type** -- The template type (see above). - **Payable To** -- The payee or description, with auto-complete from your transaction history. - **Code** -- An optional check number or reference code, with auto-complete. - **Memo** -- An optional note. - **Account** and **Envelope** -- The account and envelope assignments, which vary by template type. - **Payment** and **Deposit** -- The transaction amount. Transfer types add fields for the destination account and envelope. Multiple types add a table where you can enter the split line items. For Regular Multiple templates, account transfer line items are available only when **Enable Account Transfers in Multiples** is enabled. Those account-transfer rows reduce the main transaction amount and record the transferred amount in the other account. ## Creating Transactions from Templates Templates can be applied to new transactions in two ways: - Right-click a template and select **Create Transaction**. This opens the transaction editor with all fields pre-filled from the template. - In the transaction editor, use the **Apply or Create Template** button to apply an existing template to the current transaction or save the current transaction as a new template. # Select an Account Pick an account for the current operation. ![Select an Account](images/Select_Account.png) ## Overview The **Select Account** dialog appears when Principal Plan needs you to choose an account before proceeding. It presents your full account tree in a scrollable list. Select an account and press OK, or double-click the account. ## When It Appears The dialog opens in two situations: - **Opening an account ledger without a selection.** When you choose **View** > **Account Ledger** from the menu bar and no account is currently selected in the left panel, the dialog asks you to pick one. - **Selecting an account during an operation.** Some actions, such as choosing an account within the transaction editor or during import, use this dialog to let you browse and pick from the full account list. ## Using the Dialog The dialog shows a tree view of all your accounts, organized by group. Expand or collapse groups by clicking the arrow next to each group name. Click an account to highlight it, then click **OK** to confirm your choice. You can also double-click an account to select it and close the dialog in one step. A message below the tree explains what the selection is for. The text varies depending on which operation triggered the dialog. ## Allowed Account Choices Some operations require a regular account rather than an account group. If a group account is not allowed for the current operation, Principal Plan shows a warning and keeps the dialog open until you choose a regular account or cancel. ## Buttons | Button | Description | |---|---| | **OK** | Confirms the selected account and closes the dialog. | | **Cancel** | Closes the dialog without making a selection. | | **Help** | Opens this help topic. | # Account Properties Create or edit an account. ![Account Properties](images/Account_Properties.png) ## Overview The **Account Properties** dialog creates a new account or edits an existing one. Open it by right-clicking an account in the **Account List** and selecting **Edit Properties**, or by using the add button to create a new account. ## Details The dialog contains account details. | Field | Description | |---|---| | **Name** | The display name of the account. Must be unique and non-blank. | | **Type** | The account type, selected from a drop-down list. See the type list below. | | **Description** | An optional free-text description of the account. | | **Web Address** | An optional URL linking to the institution's website. This is used by the **Open Website** button in the **Account List** toolbar. | To enter an opening balance, create the account first, then add an opening transaction in the account ledger. ## Account Types For regular accounts, the **Type** drop-down offers 19 account types: Principal Plan treats all regular account types the same internally. The selected type only assigns the icon shown for the account. | Type | Description | |---|---| | **Checking** | A standard checking account. | | **Savings** | A savings account. | | **Credit Card** | A credit card. The balance represents the amount owed. | | **Cash** | Physical cash on hand. | | **E-Cash** | Electronic cash accounts such as PayPal or Venmo. | | **Investment** | General investment accounts. | | **Loan** | A personal or auto loan. | | **Mortgage** | A home mortgage. | | **Retirement** | Retirement accounts such as 401(k) or IRA. | | **Brokerage** | A brokerage or trading account. | | **HSA** | A Health Savings Account. | | **Crypto** | Cryptocurrency wallets and exchanges. | | **Prepaid** | Prepaid debit cards. | | **Money Market** | A money market account. | | **CD** | A certificate of deposit. | | **Business** | A business or commercial account. | | **Property** | Real estate or other property assets. | | **Insurance** | Insurance policies with a cash value. | | **Gift Card** | Gift cards and store credit. | Each type has its own icon in the account list. ## Group Accounts When creating or editing a **Group** account, the dialog behaves differently: - The **Type** drop-down shows only the **Group** option. - The **Web Address** field is hidden. Group accounts serve as organizational folders. They cannot be changed to a regular account type, and regular accounts cannot be changed to groups. ## Allowed Account Names Account names must be filled in and unique. If the name is blank, or if another account or group already uses the same name, Principal Plan shows a warning and asks you to enter a different name. ## Buttons | Button | Description | |---|---| | **OK** | Saves the changes and closes the dialog. | | **Cancel** | Discards changes and closes the dialog. | | **Help** | Opens this help topic. | # Account Activity Report Report on balances for selected accounts. ![Account Activity Report](images/Account_Activity_Report.png) ## Overview The **Account Balance** report shows the current balance and reconciled balance for selected accounts as of a chosen date. Open it by clicking the print button in the **Account List** toolbar. ## Account Selection The left side of the dialog shows a tree view of all your accounts. Check the accounts you want to include in the report. Two selection buttons are available: - **Select All Accounts** -- Checks every account in the list. - **Clear Selection** -- Unchecks all accounts. Your selections are remembered between sessions. ## Date Range The date drop-down chooses the point in time for the report: | Option | Description | |---|---| | **Everything** | Includes all transactions regardless of date. | | **End of This Month / Quarter / Year** | Balances as of the end of the current period. | | **End of Last Month / Quarter / Year** | Balances as of the end of the previous period. | | **End of 2--5 Quarters Ago** | Balances as of the end of earlier quarters. | | **As of Custom Date** | Enables a text field where you can type any date. | When you type a date directly into the date field, the drop-down automatically switches to the custom date option. ## Columns Two checkboxes control which columns appear in the report: | Column | Description | |---|---| | **Balance** | The total balance of each account as of the selected date. | | **Reconciled** | The balance considering cleared and pending transactions. | You can show both columns together or either column by itself. ## Output Options Four buttons on the side provide output options: | Button | Description | |---|---| | **Print** | Sends the report to your printer. | | **Preview** | Opens a print preview window where you can review the report before printing. | | **Copy to Clipboard** | Copies the report as tab-delimited text, suitable for pasting into a spreadsheet. | | **Export to File** | Saves the report as a CSV file. A save dialog lets you choose the location and filename. | The printed report uses a portrait layout with account names on the left and amounts right-aligned. The report title includes the selected date when a specific date is chosen. # Account Ledger The transaction register for a single account. ![Account Ledger](images/Account_Ledger.png) ## Overview The account ledger is the workspace for viewing and managing transactions in a single account. It opens as a tab when you double-click an account in the **Account List** or choose **View** > **Account Ledger** from the menu bar. The ledger header shows the account name and the current balance (or cleared balance in reconcile mode). Negative balances appear in red. ## Columns The ledger displays the columns listed below. Column visibility and width are configurable through the settings button. | Column | Description | |---|---| | **Code** | The check number or reference code. | | **Date** | The transaction date. Hovering shows the long date format as a tooltip. | | **Payable To** | The payee or description. | | **Memo** | An optional note. | | **X** (Account) | The account clearing state: blank = not cleared, * = pending, X = cleared. | | **Account** | The account name. | | **Envelope** | The envelope name. | | **Envelope/Transfer** | Shows the linked envelope name for simple transactions or the transfer target for transfers. | | **Payment** | The payment amount. A dash indicates zero. | | **Deposit** | The deposit amount. A dash indicates zero. | | **Balance** | The running account balance. Negative values appear in red. Future-dated transactions appear in a distinct color. | Most columns can be sorted by clicking the header. The Balance column cannot be sorted. ## Toolbar The toolbar across the top of the ledger provides these actions: | Button | Description | |---|---| | **Add New Transaction** | Opens the transaction editor to create a new transaction. | | **Delete Selected Transaction** | Deletes the selected transaction after confirmation. | | **Filter View** | Opens a drop-down with quick filter presets and an **Advanced** option for the full filter dialog. | | **Refresh View (F5)** | Refreshes the ledger display. | | **Quick Filter** | A text box for live filtering as you type (Ctrl+Q to focus). | | **Search and Replace Values** | Opens the search and replace dialog. | | **Web Lookup** | Searches the web for the selected transaction's payee. | | **Print Ledger** | A drop-down with **Print** and **Preview** options. | | **Export** | A drop-down with **Export Ledger** and **Copy Ledger to Clipboard** options. | | **Settings** | Opens the ledger column and display settings. | | **Help** | Opens this help topic. | ## Right-Click Menu Right-clicking a transaction shows a context menu with these actions: - **Delete** -- Deletes the selected transaction. - **Toggle Cleared** -- Cycles the account clearing state between not cleared and pending. - **Search Web** -- Searches the web for the transaction's payee. - **Insert New Simple** -- Creates a new simple transaction. - **Insert New Transfer** -- Creates a new transfer transaction. - **Insert New Multiple** -- Creates a new multi-split transaction. ## Keyboard Shortcuts | Shortcut | Action | |---|---| | F5 | Refresh the ledger view. | | Ctrl+Enter | Open the transaction editor for the selected transaction. | | Ctrl+Insert | Create a new transaction. | | Ctrl+Delete | Delete the selected transaction. | | Ctrl+X | Toggle the cleared state of the selected transaction. | | Ctrl+H | Open the search and replace dialog. | | Ctrl+Home | Jump to the first transaction. | | Ctrl+End | Jump to the last transaction. | | Ctrl+Q | Focus the quick filter text box. | ## Filtering The **Filter View** button provides quick filter presets: - **View All** -- Shows all transactions. - **View Pending** -- Shows only uncleared transactions. - **View Pending Deposits** -- Shows uncleared deposits. - **View Pending Checks** -- Shows uncleared transactions with check codes. - **View Pending Non-Checks** -- Shows uncleared non-check transactions. The **Advanced** option opens the full **Transaction View Filter and Settings** dialog with eight filter categories: - **Filter by Date** -- Any, specific date, or date range. - **Filter by Code** -- Any, checks only, non-numbers, or text search. - **Filter by Payable To** -- Any or text search. - **Filter by Other Criteria** -- Transaction type, specific envelope, or include descendants. - **Filter by Amount** -- Any, payments, deposits, specific amount, or range. - **Filter by Cleared State** -- Any, cleared, not cleared, or not cleared and pending. - **Filter by Memo** -- Any or text search. - **Filter by Import/Synchronization** -- Any, freshly imported, or not freshly imported. Text search filters support case-sensitive matching, exact matching, and regular expressions. ## Creating and Editing Transactions Double-click a transaction to open the transaction editor. Use the toolbar button or Ctrl+Insert to create a new transaction. The editor supports all four transaction types: **Simple**, **Transfer**, **Regular Multiple**, and **Multiple Envelope Transfer**. The **Payable To** field offers auto-complete from your transaction history. Selecting a match can fill other fields from the most recent matching transaction. See the **Edit Transaction** topic for full details on the transaction editor. ## Printing and Exporting The print button offers two options: - **Print Ledger** -- Sends the ledger to your printer in portrait layout. - **Preview Ledger** -- Opens a print preview window. The export button offers two options: - **Export Ledger** -- Saves the visible transactions as a CSV file. - **Copy Ledger to Clipboard** -- Copies the visible transactions as tab-delimited text for pasting into a spreadsheet. Both export options respect column visibility settings and offer an option to combine the payment and deposit columns into a single amount column. # Select an Envelope Pick an envelope for the current operation. ![Select an Envelope](images/Select_Envelope.png) ## Overview The **Select Envelope** dialog appears when Principal Plan needs you to choose an envelope before proceeding. It presents your full envelope tree in a scrollable list. Select an envelope and press OK, or double-click the envelope. ## When It Appears The dialog opens in two situations: - **Opening an envelope ledger without a selection.** When you choose **View** > **Envelope Ledger** from the menu bar and no envelope is currently selected in the left panel, the dialog asks you to pick one. - **Zero Out Envelopes.** When you use the **Zero Out** action from the envelope list, the dialog asks you to select a destination envelope to receive the transferred balance. ## Using the Dialog The dialog shows a tree view of all your envelopes, organized by their parent-child hierarchy. Expand or collapse parent envelopes by clicking the arrow next to each name. Click an envelope to highlight it, then click **OK** to confirm your choice. You can also double-click an envelope to select it and close the dialog in one step. A message below the tree explains what the selection is for. The text varies depending on which operation triggered the dialog. ## Buttons | Button | Description | |---|---| | **OK** | Confirms the selected envelope and closes the dialog. | | **Cancel** | Closes the dialog without making a selection. | | **Help** | Opens this help topic. | # Envelope Properties Create or edit an envelope. ![Envelope Properties](images/Envelope_Properties.png) ## Overview The **Envelope Properties** dialog creates a new envelope or edits an existing one. Open it by right-clicking an envelope in the **Envelope List** and selecting **Edit Properties**, or by using the add button to create a new envelope. ## Fields The dialog contains these controls: | Field | Description | |---|---| | **Name** | The display name of the envelope. Must be unique and non-blank. | | **Limit** | The watchdog threshold amount. When the envelope balance drops below this value, an alert is triggered. This field is only editable when the watchdog is turned on. | | **Watchdog toggle** | A button that enables or disables the watchdog for this envelope. When turned off, the limit field displays "**Watchdog Off**" and is disabled. When turned on, the previous limit value is restored. | | **Display Envelope Balance in Envelope List** | Controls whether the balance column in the envelope list shows a value for this envelope. | | **Include this Envelope in the Allocation Plan** | Marks the envelope for inclusion in the [Allocation Plan](Allocation_Plan.html). | | **Display Envelope Reconcile Balance in Envelope List** | Controls whether the cleared balance column in the envelope list shows a value for this envelope. | | **Description** | An optional free-text description of the envelope's purpose. | ## Watchdog Behavior The watchdog is a spending alert system. When enabled, Principal Plan monitors the envelope's balance and shows a **Watchdog Alert** whenever a transaction causes the balance to drop below the limit. - **Turning the watchdog on** restores the limit field to its previous value, enables editing, and right-aligns the amount. - **Turning the watchdog off** saves the current limit value internally, displays "**Watchdog Off**" in the field, disables editing, and centers the text. An inline description below the toggle explains: "When the Watchdog is on, you will be warned if the Envelope balance goes below the Limit." ## Allowed Envelope Values Envelope names must be filled in and unique. If the name is blank, or if another envelope already uses the same name, Principal Plan shows a warning and asks you to enter a different name. The limit and description fields do not have additional restrictions. ## Buttons | Button | Description | |---|---| | **OK** | Saves the changes and closes the dialog. | | **Cancel** | Discards changes and closes the dialog. | | **Help** | Opens this help topic. | # Envelope Activity Report Detailed activity breakdown across envelopes over a date range. ![Envelope Activity Report](images/Envelope_Activity_Report.png) ## Overview The **Envelope Activity** report shows a breakdown of allocations, expenses, and transfers for selected envelopes over a date range. Open it by clicking the print button in the **Envelope List** toolbar and selecting **Envelope Activity**. ## Envelope Selection The left side of the dialog shows a tree view of all your envelopes. Check the envelopes you want to include in the report. Three toolbar buttons control selection: - **Select All Envelopes** -- Checks every envelope. - **Clear Selection** -- Unchecks all envelopes. - **Select Allocation Plan** -- Checks only envelopes that are included in the **Allocation Plan**. Your selections are remembered between sessions. ## Date Range A drop-down offers preset date ranges: - **Custom** -- Enables editable From and To date fields. - **This Week / This Week to Date / Last Week** - **This Month / This Month to Date / Last Month** - **This Quarter / This Quarter to Date / Last Quarter** - **This Year / This Year to Date / Last Year** Selecting a preset fills in the From and To dates automatically. Editing the dates directly switches the drop-down to Custom. ## Columns Eight checkboxes control which data columns appear in the report: | Column | Description | |---|---| | **Allocations** | Positive non-transfer transactions (income allocated to the envelope). | | **Expenses** | Negative non-transfer transactions (spending from the envelope). | | **Xfers In** | Transfer money moved into the envelope. | | **Xfers Out** | Transfer money moved out of the envelope. | | **All In** | Combined total of allocations and transfers in. | | **All Out** | Combined total of expenses and transfers out. | | **Start Balance** | The envelope balance at the start of the date range. | | **End Balance** | The envelope balance at the end of the date range, computed as Start + All In - All Out. | ## Extrapolate or Average A drop-down scales the reported values to a normalized rate: - **None (Gross)** -- Shows raw totals for the selected period. - Per day, per week, per month, per quarter, or per year. Start and end balances are not affected by scaling. ## Output Options | Button | Description | |---|---| | **Print** | Sends the report to your printer. | | **Preview** | Opens a print preview window. | | **Copy to Clipboard** | Copies the report as tab-delimited text. | | **Export to File** | Saves the report as a CSV file. | All settings are remembered between sessions. # Envelope Summary Report A summary of envelope names and balances. ![Envelope Summary Report](images/Envelope_Summary_Report.png) ## Overview The **Envelope Summary** report lists selected envelopes with their current balances. Open it by clicking the print button in the **Envelope List** toolbar and selecting **Envelope Summary**. ## Envelope Selection The left side of the dialog shows a tree view of all your envelopes. Check the envelopes you want to include in the report. Three toolbar buttons control selection: - **Select All Envelopes** -- Checks every envelope. - **Clear Selection** -- Unchecks all envelopes. - **Select Allocation Plan** -- Checks only envelopes that are included in the **Allocation Plan**. Your selections are remembered between sessions. ## Report Size A **Report Size:** drop-down on the right side chooses the paper format: | Format | Description | |---|---| | **Standard** | Letter-size portrait with column headers and page numbers. | | **Business Cards** | Compact portrait cards, nine per page. | | **Business Cards (Avery)** | Landscape cards formatted for Avery label sheets, ten per page. | | **Organizer 3.75 x 6.75** | Small organizer pages in landscape. | | **Organizer 4.25 x 6.75** | Medium organizer pages in landscape. | | **Organizer 5.50 x 8.50** | Large organizer pages in landscape. | The standard format includes a header row with "Envelope" and "Balance" column labels, a report title, and a page/date footer. The compact card formats omit headers for a more condensed layout. Your format selection is remembered between sessions. ## Output Options | Button | Description | |---|---| | **Print** | Sends the report to your printer. | | **Preview** | Opens a print preview window. | | **Copy to Clipboard** | Copies the report as tab-delimited text (envelope name and balance). | | **Export to File** | Saves the report as a CSV file. | # Envelope Ledger The transaction register for a single envelope. ![Envelope Ledger](images/Envelope_Ledger.png) ## Overview The envelope ledger shows all transactions assigned to a single envelope. It opens as a tab when you double-click an envelope in the **Envelope List** or choose **View** > **Envelope Ledger** from the menu bar. The envelope ledger shares the same layout and most of the same functionality as the account ledger. This topic covers the differences. See the [Account Ledger](Account_Ledger.html) topic for full details on columns, toolbar buttons, keyboard shortcuts, and filtering. ## Differences from the Account Ledger ### Column Headers The ledger displays the columns listed in the [Account Ledger](Account_Ledger.html) topic, with the header differences listed below. Column visibility and width are configurable through the settings button. | Account Ledger | Envelope Ledger | |---|---| | **Payable To** | **Payable To/Description** | | **Envelope/Transfer** | **Account/Transfer** | The details column shows the linked account name (instead of the linked envelope name) for simple transactions. For transfers, it shows the transfer target. ### Clearing Clicking the cleared column or using **Toggle Cleared** toggles the **envelope** clearing state rather than the account clearing state. The two clearing states are independent, so clearing a transaction in the envelope ledger does not affect its account clearing state. ### Context Menu The right-click menu offers **Insert New Multiple Transfer** instead of Insert New Multiple. This reflects that multi-split transactions created from the envelope ledger are envelope splits rather than account splits. ### Toolbar and Appearance The filter button tooltip reads **Filter Ledger** instead of **Filter View**. The ledger background uses a distinct color to visually differentiate it from the account ledger. ## Everything Else All other features work identically to the account ledger: - The same configurable columns appropriate to the envelope ledger (with the header differences noted above). - The same toolbar buttons for creating, deleting, filtering, searching, printing, and exporting transactions. - The same keyboard shortcuts (F5, Ctrl+Enter, Ctrl+Insert, Ctrl+Delete, Ctrl+X, Ctrl+H, Ctrl+Q, Ctrl+Home, Ctrl+End). - The same filter presets (**View All**, **View Pending**, etc.) and the same advanced filter dialog with eight filter categories. - The same print, preview, export, and copy-to-clipboard functionality. # Delete an Envelope Safely remove an envelope from your file. ![Delete an Envelope](images/Delete_Envelope.png) ## Overview When you delete an envelope that contains transactions or child envelopes, Principal Plan needs to know where to move those items. The **Delete Envelope** dialog asks you to select a destination envelope before the deletion proceeds. ## When It Appears The dialog appears only when the envelope being deleted is not empty -- it has transactions assigned to it, or it has child envelopes nested inside it. If the envelope is empty (no transactions and no children), a simple confirmation prompt appears instead and no destination is needed. ## Using the Dialog The dialog shows a tree view of your full envelope hierarchy. Click an envelope to select it as the destination for the items being moved, then click **OK**. You can also double-click an envelope to select it and confirm in one step. A note at the top of the dialog explains: "When deleting Envelopes that contain transactions or other Envelopes, you must select a new Envelope to move items into." All transactions currently assigned to the deleted envelope will be reassigned to the destination envelope. Any child envelopes will be moved under the destination envelope. ## Allowed Destination Envelopes Choose a destination envelope before clicking **OK**. The destination must be different from the envelope being deleted, and it cannot be one of that envelope's descendants. The root envelope cannot be deleted. If you try to delete it, Principal Plan shows a warning and cancels the operation before this dialog opens. ## Buttons | Button | Description | |---|---| | **OK** | Moves items to the selected envelope and deletes the original. | | **Cancel** | Cancels the deletion. | | **Help** | Opens this help topic. | # Edit a Transaction Enter or edit a single transaction. ![Edit a Transaction](images/Edit_Transaction.png) ## Overview The **Edit Transaction** dialog creates and edits transactions. It opens when you double-click a transaction in the ledger, press Ctrl+Enter, or use the add button to create a new transaction. ## Common Fields Every transaction type shares these fields at the top of the dialog: | Field | Description | |---|---| | **Transaction Type** | A drop-down to select the transaction type (see below). | | **Code** | An optional check number or reference code. The **+** button fills in the next check number for the selected account. Auto-complete suggests codes from your history. | | **Date** | The transaction date. A calendar button opens a date picker. | | **Payable To** | The payee or description. Auto-complete suggests matches from your transaction history. | | **Payment** | The payment amount. Entering a negative value moves it to the deposit side. | | **Deposit** | The deposit amount. Entering a negative value moves it to the payment side. | | **Memo** | An optional note. | ## Transaction Types The **Transaction Type** drop-down switches the dialog between four layouts: ### Simple The default type for everyday transactions. Adds two fields: - **Account** -- The account the transaction affects. - **Envelope** -- The envelope the transaction draws from or credits. ### Transfer A movement of money between accounts, envelopes, or both at the same time. Adds: - **Account Transfer** -- Checkbox that enables Account From and Account To fields. - **Envelope Transfer** -- Checkbox that enables Envelope From and Envelope To fields. - A second set of Code, Date, Payable To, Payment, Deposit, and Memo fields for the counterpart side of the transfer. The transfer arrows and section labels (**Transfer From** / **Transfer To**) adjust automatically based on whether the payment or deposit side has a value. ### Regular Multiple A single transaction split across multiple line items. Adds: - **Account** -- The account for the parent transaction. - A line item table where each row is an envelope allocation or, when enabled, an account transfer with its own amount. - Add and delete buttons for managing line items. - A running total that updates as you add or change items. By default, Regular Multiple rows allocate the transaction amount across envelopes. Account transfer rows are available only when **Enable Account Transfers in Multiples** is enabled in Settings. An account-transfer row moves that part of the transaction to another account and reduces the main transaction amount. For example, a $1,000 paycheck with a $100 account-transfer row is recorded as a $900 deposit in the paycheck account plus a $100 transfer to the other account. ### Multiple Envelope Transfer A transfer split across multiple envelope assignments. Adds: - **Envelope** -- The envelope for the parent transaction. - A line item table for the split. - Add and delete buttons. - A running total. ## Toolbar Buttons A toolbar across the top of the dialog provides quick actions: | Button | Description | |---|---| | **Add New Transaction** | Saves the current transaction and starts a new blank one. | | **Delete Transaction** | Deletes the current transaction after confirmation. | | **Clone Transaction** | Saves a copy of the current transaction as a new record. | | **Apply or Create Template** | Opens a menu listing saved templates. Selecting one fills the dialog with the template's values. The menu also includes **Save Transaction as Template** to save the current transaction as a new template. | | **Previous Transaction** | Saves and navigates to the previous transaction in the ledger. | | **Next Transaction** | Saves and navigates to the next transaction in the ledger. | ## Bottom Buttons | Button | Description | |---|---| | **Save & Close** | Saves the transaction and closes the dialog. | | **Save & New** | Saves the transaction and opens a new blank transaction. | | **Cancel** | Closes the dialog without saving. | | **Revert** | Restores the transaction to the state it was in when the dialog opened. | | **Help** | Opens this help topic. | ## Auto-Complete and Auto-Fill The **Payable To** field provides context-aware auto-complete from your transaction history. When you select a match, the dialog can fill other fields from the most recent matching transaction. The auto-fill behavior is configurable: - **All fields** -- Fills code, memo, account, envelope, and amounts. - **All fields with scaled amounts** -- Same as above, but scales line item amounts proportionally to match the current total. - **Text fields only** -- Fills only code, payable to, and memo. ## Next Check Number The **+** button next to the **Code** field inserts the next sequential check number for the current account. After filling the code, focus moves to the date field. # Transaction Filter Filter the transactions displayed in a ledger. ![Transaction Filter](images/Transaction_Filter.png) ## Overview The **Transaction View Filter and Settings** dialog controls which transactions are visible in the ledger. Open it by clicking the filter button in the ledger toolbar and selecting **Advanced**. The dialog contains eight filter groups arranged in a grid. Each group is independent, so you can combine filters from multiple groups to narrow the display precisely. ## Filter by Date - **Any Value** -- Shows transactions from all dates. - **Specific Date** -- Shows transactions on a single date. A calendar button opens a date picker. - **Date Range** -- Shows transactions within a From and To range. Both fields have calendar buttons. ## Filter by Amount - **Any Value** -- Shows all amounts. - **Any Payment** -- Shows only payments (negative amounts). - **Any Deposit** -- Shows only deposits (positive amounts). - **Specific Amount** -- Shows transactions matching an exact amount. - **Amount Range** -- Shows transactions within a From and To amount range. ## Filter by Code - **Any Value** -- Shows all codes. - **Checks (Numbers)** -- Shows only transactions with numeric codes (check numbers). - **Non-Numbers** -- Shows transactions with non-numeric or blank codes. - **Search Text** -- Shows transactions where the code matches a search string. - Match options: **Case Sensitive**, **Exact Text**, **Regex**. ## Filter by Cleared State - **Any Value** -- Shows all clearing states. - **Cleared** -- Shows only cleared transactions. - **Not Cleared** -- Shows only uncleared transactions. - **Not Cleared and Pending** -- Shows uncleared and pending transactions. ## Filter by Payable To - **Any Value** -- Shows all payees. - **Search Text** -- Shows transactions where the payee matches a search string. - Match options: **Case Sensitive**, **Exact Text**, **Regex**. ## Filter by Memo - **Any Value** -- Shows all memos. - **Search Text** -- Shows transactions where the memo matches a search string. - Match options: **Case Sensitive**, **Exact Text**, **Regex**. ## Filter by Other Criteria - **Any Transaction Type** -- Shows all transaction types. - **Multiples Only** -- Shows only multi-split transactions. - **Transfers Only** -- Shows only transfer transactions. - **Envelope / Account** -- Shows transactions assigned to a specific envelope (in account ledgers) or account (in envelope ledgers), selected from a drop-down. - **Include Descendant Envelopes** -- When filtering by envelope, also includes transactions in child envelopes. ## Filter by Import/Synchronization - **Any Value** -- Shows all transactions. - **Freshly Imported or Synchronized** -- Shows only recently imported transactions. - **Not Freshly Imported or Synchronized** -- Hides recently imported transactions. ## Text Search Options The Code, Payable To, and Memo filters each support three matching options: - **Case Sensitive** -- Distinguishes between uppercase and lowercase letters. - **Exact Text** -- Requires the entire field to match, not just a substring. - **Regex** -- Treats the search text as a regular expression. Typing in any text field automatically selects the corresponding search option. ## Buttons | Button | Description | |---|---| | **OK** | Applies the filter settings and closes the dialog. | | **Cancel** | Discards changes and closes the dialog. | | **Help** | Opens this help topic. | # Search and Replace Find and replace text across transactions. ![Search and Replace](images/Search_Replace.png) ## Overview The **Search and Replace** dialog finds and replaces text across all visible transactions in the current ledger. Open it from the ledger toolbar button or by pressing Ctrl+H. ## Fields | Field | Description | |---|---| | **Search Text** | The text to find. | | **Replace With** | The replacement text. Leave empty to delete matched text. | ## Search Scope Three checkboxes control which transaction fields are searched: | Checkbox | Description | |---|---| | **Include Code** | Searches in the code field. Off by default. | | **Include Memo** | Searches in the memo field. Off by default. | | **Include Payable To/Description** | Searches in the payee field. On by default. | You can enable any combination of these to search across multiple fields at once. ## Match Options Three checkboxes refine how the search text is matched: | Option | Description | |---|---| | **Case Sensitive** | Distinguishes between uppercase and lowercase letters. Off by default. | | **Entire Text** | Requires the entire field to match the search text, not just a substring. Off by default. | | **Regex** | Treats the search text as a regular expression with capture group support. Off by default. | ## How It Works When you click **OK**, the operation runs immediately on all transactions currently visible in the ledger. Each selected field in each transaction is checked against the search text, and matching text is replaced. There is no preview or per-transaction confirmation step. The replacement happens in one pass across all visible transactions. After completion, a message reports how many transactions were modified (for example, "3 Transactions Modified"). The ledger updates in place to reflect the changes. ## Tips - **Filter first.** Use the ledger filter to narrow the visible transactions before running a search and replace. The operation only affects transactions that are currently displayed. - **Use regex for complex patterns.** With the **Regex** option enabled, you can use regular expression syntax for advanced matching, including capture groups in the replacement text. - **Combine with Entire Text.** Enable both **Regex** and **Entire Text** to anchor the pattern to the full field value. ## Buttons | Button | Description | |---|---| | **OK** | Runs the search and replace operation. | | **Cancel** | Closes the dialog without making changes. | | **Help** | Opens this help topic. | # Allocation Plan Automate how deposits are divided across envelopes. ![Allocation Plan](images/Allocation_Plan.png) ## Overview The **Allocation Plan** is a grid that maps your envelopes to one or more income templates. Each cell holds the amount that should be allocated to a given envelope when that income arrives. Open the Allocation Plan from the View menu or by pressing the toolbar button. ## Layout The left column lists every envelope that has **Include in Allocation Plan** enabled in its properties. Up to eight template columns appear to the right, one for each income source you have defined. Each cell in the grid holds a currency amount representing how much of that template's income goes to that envelope. A totals row at the bottom of each column shows the sum of all allocations for that template. The **Restore Envelope List Sort Order** toolbar button restores the envelope rows to their original sort order. ## Span Normalization Each template has a frequency (for example, twice per month). The plan converts every template to a common span so you can compare allocations across different pay schedules. A drop-down switches the display span between four options: - **View by Day** -- Shows daily amounts. - **View by Week** -- Shows weekly amounts. - **View by Month** -- Shows monthly amounts. - **View by Year** -- Shows yearly amounts. Changing the view span recalculates the displayed values for comparison. The underlying per-occurrence amounts are preserved. ## Adding and Removing Templates - **Add** -- Click **Add or Create Template** to open a drop-down menu. Existing templates that are not already in the plan are listed for quick selection. Choose **Add New Template** to create a new income template from scratch. The plan supports up to eight template columns. - **Remove** -- Click **Remove Template** and choose a template from the drop-down menu to remove it from the plan, or choose **Remove All Templates** to remove them all. The template itself is not deleted; it is only removed from the plan grid. ## Editing Cells Click any cell in the grid to type an amount. ## Output Options | Button | Description | |---|---| | **Print Allocation Plan** | A drop-down with **Print Plan** and **Preview Plan** options. | | **Export Allocation Plan** | A drop-down with **Export Plan** (saves as CSV) and **Copy Plan to Clipboard** (tab-delimited text) options. | ## Buttons | Button | Description | |---|---| | **OK** | Saves changes and closes the dialog. | | **Cancel** | Closes the dialog without saving. | | **Help** | Opens this help topic. | # Edit a Template Modify a saved transaction template. ![Edit a Template](images/Edit_Template.png) ## Overview The **Edit Transaction Template** dialog creates and modifies transaction templates. Templates store reusable transaction fields that you can apply when entering new transactions. Open a template for editing by double-clicking it in the template list, or by selecting a template and pressing Enter. ## Transaction Type A drop-down at the top of the dialog selects the template type. The four types match the transaction types available in the [Edit a Transaction](Edit_Transaction.html) dialog: | Type | Description | |---|---| | **Simple** | A single account and envelope assignment. | | **Transfer** | A movement between accounts, envelopes, or both. | | **Regular Multiple** | A single transaction split across multiple line items. | | **Multiple Envelope Transfer** | A transfer split across multiple envelope assignments. | The dialog layout changes to show the fields appropriate for the selected type. ## Common Fields Every template type shares these fields: | Field | Description | |---|---| | **Name:** | The template name. | | **Payable To:** | The payee or description for the template. | | **Payment** | The payment amount. | | **Deposit** | The deposit amount. | | **Memo** | An optional note. | ## Frequency The frequency section controls how often the template recurs: - **Count** -- The number of occurrences per period (for example, 2). - **Period** -- The interval between groups of occurrences (for example, 1). - **Span** -- The time unit: Day, Week, Month, or Year. Together these read as "N time(s), every M [span]." For example, "1 time, every 2 Weeks" describes a biweekly template. The span label switches between singular and plural automatically. ## Allocation Plan The **Include in Allocation Plan** checkbox adds this template as a column in the [Allocation Plan](Allocation_Plan.html). When enabled, the template appears in the plan grid and its amount is distributed across envelopes according to the plan. Only these template types can be included in the allocation plan: - **Regular Multiple** - **Multiple Envelope Transfer** ## Allowed Template Names The **Name:** field is the template name. It must be filled in and unique across all templates. If it is blank, or if another template already uses the same name, Principal Plan shows a warning and asks you to enter a different name. ## Buttons | Button | Description | |---|---| | **OK** | Saves the template and closes the dialog. | | **Cancel** | Closes the dialog without saving. | | **Help** | Opens this help topic. | # New Allocation Plan Template Create a new income template for the Allocation Plan. ![New Allocation Plan Template](images/New_Allocation_Plan_Template.png) ## Overview The **Create Income Template** dialog creates a new transaction template and adds it directly to the [Allocation Plan](Allocation_Plan.html) as a new column. It opens when you click **Add New Template** from the add button menu in the Allocation Plan dialog. ## Fields | Field | Description | |---|---| | **Payable To:** | The name of the template. Pre-filled as "New Template." This name also becomes the template's payee field and appears as the column header in the Allocation Plan. | | **Type** | The template type. Two options are available: **Regular Multiple** (a deposit or payment split across envelope allocations, with optional account-transfer rows when enabled) and **Multiple Envelope Transfer** (an envelope-based transfer). | | **Frequency:** | How often the income recurs, expressed as a count, period, and span. For example, "1 time, every 1 Month" describes a monthly template. The span label switches between singular and plural automatically. | ## Allowed Template Names The **Payable To:** field is the template name. It must be filled in and unique across all existing templates, including templates that are not currently in the Allocation Plan. If it is blank, or if another template already uses the same name, Principal Plan shows a warning and asks you to enter a different name. ## Buttons | Button | Description | |---|---| | **OK** | Creates the template and adds it to the Allocation Plan. | | **Cancel** | Cancels template creation. | # Import Transactions Bring transactions in from a bank file. ![Import Transactions](images/Import_Transactions.png) ## Overview Principal Plan imports transactions from files downloaded from your bank or financial institution. Open the import dialog from File > **Import Transactions** and select a file. Three file formats are supported: | Format | Extensions | Description | |---|---|---| | CSV | .csv | Comma-separated values. Supports US and international date formats. | | QIF | .qif | Quicken Interchange Format. | | OFX / QFX | .ofx, .qfx | Open Financial Exchange and Quicken Financial Exchange. | ## The Import Dialog The import dialog has two tabs: - **Basic** -- Select the target account, default envelope, and file handling options. See [Import Transactions — Basic](Import_Transactions_Basic.html) for details. - **Advanced** -- Configure duplicate detection, field transformations, and AI envelope matching. See [Import Transactions — Advanced](Import_Transactions_Advanced.html) for details. All settings are saved per account and restored the next time you import into that account. ## Import Workflow 1. Select a file using the file picker (or let the file watch feature open the dialog automatically). 2. Choose the target account on the Basic tab. 3. Adjust the default envelope and any advanced settings as needed. 4. Click **OK** to run the import. During import, Principal Plan parses the file and compares each transaction with existing records. When **Smart Import** is enabled, matching transactions are linked rather than duplicated, and unmatched cleared transactions within the matching window can be uncleared. New transactions are created with a pending status. After import, the account ledger opens filtered to show the newly imported transactions. Because imported files usually come from your bank, this is a good time to reconcile the account balance. See [Reconciling an Account](Reconciling.html) for the reconciliation workflow. ## Checkpoint If **Create Checkpoint Before Import** is enabled in [Settings — Accounts](Settings_Accounts.html), a checkpoint of your data file is saved before the import begins. This gives you a restore point if the import produces unexpected results. ## File Watch When both **Delete File After Import** and **Watch for this File** are enabled, Principal Plan monitors the file path after import. If the file reappears (for example, from an automated bank download), the import dialog opens automatically for that account. This supports recurring hands-free imports. ## Buttons | Button | Description | |---|---| | **OK** | Runs the import. | | **Cancel** | Closes the dialog without importing. | | **Help** | Opens this help topic. | # Import Transactions — Basic The Basic tab of the Import dialog. ![Import Transactions — Basic](images/Import_Transactions_Basic.png) ## Overview The Basic tab of the Import Transactions dialog contains the essential settings for every import: which account to target, which envelope to assign by default, and how to handle the source file after import. ## Fields | Field | Description | |---|---| | **Import File** | A read-only field showing the full path of the file being imported. | | **Account** | A drop-down listing all accounts. You must select an account before the import can proceed. The remaining controls on this tab are disabled until an account is chosen. | | **Default Envelope:** | The envelope assigned to imported transactions that are not matched by AI envelope matching or by an existing transaction. | | **Code +:** | The transaction type code that identifies deposits in the import file (default: "credit"). Used when the file has a single amount column with a type indicator rather than separate payment and deposit columns. | | **Code -:** | The transaction type code that identifies payments in the import file (default: "debit"). | | **Delete File After Import** | When checked, the source file is removed from disk after a successful import. Enabling this option makes **Watch for this File** available. | | **Watch for this File** | When checked, Principal Plan monitors the file path and automatically reopens the import dialog if the file reappears. Only available when **Delete File After Import** is also checked. This supports recurring automated bank downloads. | ## Per-Account Settings All Basic tab settings are saved on the selected account. The next time you import into the same account, the dialog restores your previous choices. Selecting a different account in the drop-down loads that account's saved settings. # Import Transactions — Advanced The Advanced tab of the Import dialog. ![Import Transactions — Advanced](images/Import_Transactions_Advanced.png) ## Overview The Advanced tab of the Import Transactions dialog provides duplicate detection, field transformations, and AI-powered envelope matching. These settings fine-tune how imported transactions are processed and matched against your existing records. ## Smart Import The **Smart Import** group is a toggleable section that enables automatic duplicate detection. When enabled, imported transactions are compared against existing records using amount, date proximity, payee similarity, and optionally check number uniqueness. | Setting | Description | |---|---| | **Unclear Missing Transactions** | Unclears existing cleared transactions within the matching window that have no corresponding imported transaction. This helps flag transactions that may have been removed by the bank. | | **Assume Check Numbers are Unique** | Treats check numbers as unique identifiers when matching. Two transactions with the same check number are considered the same record. | | **Max Valid Check Number** | Sets the highest check number the importer treats as a real check. Numbers above this threshold are ignored during check-number matching. | | **Matching Threshold:** | Controls how closely an imported transaction must resemble an existing one to be considered a match. A lower value requires closer similarity. | ## Data Transformation The **Data Transformation** group contains field-level corrections that adjust the imported data before it is written to the ledger. | Setting | Description | |---|---| | **Swap Payable To and Memo** | Exchanges the payee and memo fields. Useful when a bank file stores the description in the memo column. | | **Swap Payment and Deposit** | Exchanges the payment and deposit amounts. Useful when a bank file reverses the sign convention. | | **Use dd/mm/yyyy Date Format** | Parses dates in day/month/year order instead of month/day/year. Enable this for international bank files. | | **AI Envelope Matching** | Automatically assigns envelopes to imported transactions based on payee similarity to past transactions. | | **Score:** | The minimum similarity score an AI envelope match must reach to be applied. Higher values require closer matches. | | **Days:** | The number of days of transaction history the AI examines when looking for payee matches. | | **Payable Regex Filter:** | A regular expression applied to the payee field before matching. Use this to strip bank-added prefixes or suffixes that interfere with matching. | | **Memo Regex Filter:** | A regular expression applied to the memo field before matching. | ## Per-Account Settings All Advanced tab settings are saved on the selected account and restored when you next import into the same account. # Print Preview Preview transaction listings and reports before printing. ![Print Preview](images/Print_Preview.png) ## Overview The Print Preview window displays a rendered view of a report or ledger listing before you send it to the printer. It opens when you click **Preview** in any report dialog or ledger print option. ## Toolbar The toolbar across the top of the window provides navigation and zoom controls: | Button | Description | |---|---| | **Close** | Closes the preview window. | | **Print** | Sends the previewed document to your printer. | | **Go to First Page** | Jumps to the first page. | | **Go to Previous Page** | Moves back one page. | | **Page Number** | A text field showing the current page number. Type a number and press Enter to jump directly to that page. | | **Go to Page** | Jumps to the page number entered in the field. | | **Go to Next Page** | Moves forward one page. | | **Go to Last Page** | Jumps to the last page. | | **Fit Whole Page in View** | Scales the view so the entire page is visible at once. | | **Fit Page Width in View** | Scales the view so the page fills the window width. | | **Zoom In** | Increases the zoom level. | | **Zoom Out** | Decreases the zoom level. | | **Print Preview Help** | Opens this help topic. | ## Keyboard Shortcuts - **Ctrl+Scroll Wheel** -- Zooms in and out of the preview. # Settings Application preferences. ![Settings](images/Settings.png) ## Overview The Principal Plan Settings dialog controls application-wide preferences. Open it from File > Settings. The dialog contains six tabs: | Tab | Description | |---|---| | **Application** | Language, file handling, ledger behavior, export options, and list view layout. See [Settings — Application](Settings_Application.html). | | **Accounts** | Account list display, ledger column visibility, import, and transfer options. See [Settings — Accounts](Settings_Accounts.html). | | **Envelopes** | Envelope list display, watchdog indicators, and ledger column visibility. See [Settings — Envelopes](Settings_Envelopes.html). | | **Backup** | Automatic backup toggle, retention depth, and backup directory. See [Settings — Backup](Settings_Backup.html). | | **Messages** | Toggle individual confirmation and warning dialogs. See [Settings — Messages](Settings_Messages.html). | | **Search** | Select the preferred web search engine. See [Settings — Search](Settings_Search.html). | Each tab has its own help topic with full details on every setting. ## Buttons | Button | Description | |---|---| | **OK** | Saves all changes across all tabs and closes the dialog. | | **Cancel** | Closes the dialog without saving. | | **Help** | Opens this help topic. | # Settings — Application General application preferences. ![Settings — Application](images/Settings_Application.png) ## Overview The Application tab of the Settings dialog controls language, file handling, ledger behavior, export formatting, and list view layout. ## Language | Setting | Description | |---|---| | **Language** | Selects the display language. Available options are English, Deutsch, Español, Français, Italiano, and Português. The change takes effect after restarting the application. | ## File Handling | Setting | Description | |---|---| | **Automatically Open Last File** | When enabled, Principal Plan reopens the most recently used file at startup. | | **Automatically Save File every** _N_ minutes | When enabled, the file is saved automatically at the specified interval. The minute field is only active when the checkbox is checked. | ## Transaction Ledgers | Setting | Description | |---|---| | **Auto-fill all details** | When entering a new transaction, all fields are copied from the most recent matching payee transaction. | | **Auto-fill text fields only** | Only text fields (payee, memo, code) are auto-filled; amounts are not copied. | | **Auto-fill all and scale the amounts** | All fields are auto-filled and line item amounts are scaled proportionally to match the current total. This is the default. | | **Lock Ledgers** | Prevents editing transactions in all ledgers until explicitly unlocked. | | **Sort Ascending** | Sorts ledger transactions in ascending date order. | ## Transaction Ledger Export | Setting | Description | |---|---| | **Include Running Balance** | Adds a running balance column to exported ledger files. | | **Combine Payment & Deposit Columns** | Merges the Payment and Deposit columns into a single Amount column on export. | ## List Views | Setting | Description | |---|---| | **Display Lists in Tabs** | The account list and envelope list are shown in separate tabs. This is the default. | | **Display Lists Stacked** | The account list and envelope list are stacked vertically in a single pane. | A **Defaults** button resets all Application tab settings to their factory values. # Settings — Accounts Account list and ledger display options. ![Settings — Accounts](images/Settings_Accounts.png) ## Overview The Accounts tab of the Settings dialog controls what information is displayed in the account list sidebar, which columns appear in the account ledger, and import-related options. ## Account List These checkboxes control what is shown next to each account in the sidebar: | Setting | Description | |---|---| | **Display Balance** | Shows the account balance. | | **Display Cleared Balance** | Shows the cleared (reconciled) balance. | ## Account Ledger Columns Nine checkboxes control which columns are visible in the account ledger. The default state is shown in parentheses: | Column | Default | |---|---| | **Code** | On | | **Date** | On | | **Memo** | Off | | **Account** | Off | | **Envelope/Transfer** | On | | **Account Cleared** | On | | **Payment** | On | | **Deposit** | On | | **Balance** | On | ## Import | Setting | Description | |---|---| | **Create Checkpoint Before Import** | Automatically saves a checkpoint of your data file before any import operation. This provides a restore point if the import produces unexpected results. | ## Other Settings | Setting | Description | |---|---| | **Enable Account Transfers in Multiples** | Allows Regular Multiple transactions to include account-transfer rows. Each account-transfer row moves part of the transaction amount to another account and reduces the main transaction amount. | A **Defaults** button resets all Accounts tab settings to their factory values. # Settings — Envelopes Envelope list and ledger display options. ![Settings — Envelopes](images/Settings_Envelopes.png) ## Overview The Envelopes tab of the Settings dialog controls what information is displayed in the envelope list sidebar and which columns appear in the envelope ledger. ## Envelope List These checkboxes control what is shown next to each envelope in the sidebar: | Setting | Description | |---|---| | **Display Balance** | Shows the envelope balance. | | **Display Cleared Balance** | Shows the cleared (reconciled) balance. | | **Display Watchdogs** | Shows watchdog indicators next to envelopes that have a watchdog limit set. | | **Indicate Bundles With Transactions** | Marks bundle (group) envelopes that have transactions assigned directly to them. Transactions on bundle envelopes can indicate a data organization issue. | ## Envelope Ledger Columns Nine checkboxes control which columns are visible in the envelope ledger. The default state is shown in parentheses: | Column | Default | |---|---| | **Code** | On | | **Date** | On | | **Memo** | Off | | **Envelope** | Off | | **Account/Transfer** | On | | **Envelope Cleared** | On | | **Payment** | On | | **Deposit** | On | | **Balance** | On | A **Defaults** button resets all Envelopes tab settings to their factory values. # Settings — Backup Automatic backup settings. ![Settings — Backup](images/Settings_Backup.png) ## Overview The Backup tab of the Settings dialog controls automatic file backup. When enabled, Principal Plan creates a backup copy of your data file each time you save. ## Settings | Setting | Description | |---|---| | **Automatically Create Backups** | The master toggle for the backup feature. When unchecked, no automatic backups are created and the remaining settings on this tab are disabled. | | **Backup Depth** | The number of backup copies to keep (1--100). When a new backup is created and the count exceeds this limit, the oldest backup is discarded. The default is 5. | | **Backup Directory** | The folder where backup files are stored. Click the browse button to select a directory. If the backup directory is unavailable when saving, an error message appears and the save is aborted to protect your data. | # Settings — Messages Which prompts and confirmations to show. ![Settings — Messages](images/Settings_Messages.png) ## Overview The Messages tab of the Settings dialog controls which confirmation and warning dialogs Principal Plan displays. Unchecking a message suppresses it; the underlying action still occurs, but without a prompt. ## Display These Messages | Setting | Description | |---|---| | **Envelope watchdog alert** | Shows a warning when an envelope balance drops below its watchdog limit. | | **Altered amount in Allocation Plan** | Shows a notification when the Allocation Plan normalizes cell values after you change an amount. | | **Import checkpoint confirmation** | Shows a confirmation when a checkpoint is created before an import. | All three are enabled by default. A **Defaults** button restores all Messages tab settings to their factory values. # Settings — Search Default web search engine. ![Settings — Search](images/Settings_Search.png) ## Overview The Search tab of the Settings dialog selects the web search engine used when you perform a search from within Principal Plan. ## Search Engines Four search engines are available. Select one: | Engine | Description | |---|---| | **Bing** | Searches using Microsoft Bing. | | **DuckDuckGo** | Searches using DuckDuckGo. | | **Google** | Searches using Google. | | **Yahoo** | Searches using Yahoo. | The selected engine is used whenever Principal Plan opens a web search in your default browser.